Mcmc.Proposal

Creation date: Wed May 20 13:42:53 2020.

Proposals

newtype PName

Proposal name.

Constructors

PName

Fields

• fromPName :: String

Instances

Eq PName

Defined in Mcmc.Proposal

Methods

(==) :: PName -> PName -> Bool

(/=) :: PName -> PName -> Bool

Ord PName

Defined in Mcmc.Proposal

Methods

compare :: PName -> PName -> Ordering

(<) :: PName -> PName -> Bool

(<=) :: PName -> PName -> Bool

(>) :: PName -> PName -> Bool

(>=) :: PName -> PName -> Bool

max :: PName -> PName -> PName

min :: PName -> PName -> PName

Show PName

Defined in Mcmc.Proposal

Methods

showsPrec :: Int -> PName -> ShowS

show :: PName -> String

showList :: [PName] -> ShowS

Semigroup PName

Defined in Mcmc.Proposal

Methods

(<>) :: PName -> PName -> PName

sconcat :: NonEmpty PName -> PName

stimes :: Integral b => b -> PName -> PName

Monoid PName

Defined in Mcmc.Proposal

Methods

mempty :: PName

mappend :: PName -> PName -> PName

mconcat :: [PName] -> PName

newtype PDescription

Proposal description.

Constructors

PDescription

Fields

• fromPDescription :: String

Instances

Eq PDescription

Defined in Mcmc.Proposal

Methods

(==) :: PDescription -> PDescription -> Bool

(/=) :: PDescription -> PDescription -> Bool

Ord PDescription

Defined in Mcmc.Proposal

Methods

compare :: PDescription -> PDescription -> Ordering

(<) :: PDescription -> PDescription -> Bool

(<=) :: PDescription -> PDescription -> Bool

(>) :: PDescription -> PDescription -> Bool

(>=) :: PDescription -> PDescription -> Bool

max :: PDescription -> PDescription -> PDescription

min :: PDescription -> PDescription -> PDescription

Show PDescription

Defined in Mcmc.Proposal

Methods

showsPrec :: Int -> PDescription -> ShowS

show :: PDescription -> String

showList :: [PDescription] -> ShowS

data PWeight

The positive weight determines how often a Proposal is executed per iteration of the Markov chain. Abstract data type; for construction, see pWeight.

Instances

Eq PWeight

Defined in Mcmc.Proposal

Methods

(==) :: PWeight -> PWeight -> Bool

(/=) :: PWeight -> PWeight -> Bool

Ord PWeight

Defined in Mcmc.Proposal

Methods

compare :: PWeight -> PWeight -> Ordering

(<) :: PWeight -> PWeight -> Bool

(<=) :: PWeight -> PWeight -> Bool

(>) :: PWeight -> PWeight -> Bool

(>=) :: PWeight -> PWeight -> Bool

max :: PWeight -> PWeight -> PWeight

min :: PWeight -> PWeight -> PWeight

Show PWeight

Defined in Mcmc.Proposal

Methods

showsPrec :: Int -> PWeight -> ShowS

show :: PWeight -> String

showList :: [PWeight] -> ShowS

pWeight :: Int -> PWeight

Check if the weight is positive.

Call error if weight is zero or negative.

data PDimension

Proposal dimension.

The number of affected, independent parameters.

The dimension is used to calculate the optimal acceptance rate, and does not have to be exact.

Usually, the optimal acceptance rate of low dimensional proposals is higher than for high dimensional ones. However, this is not always true (see below).

Further, optimal acceptance rates are still subject to controversies. To my knowledge, research has focused on random walk proposals with multivariate normal distributions of dimension d. In this case, the following acceptance rates are desired:

• one dimension: 0.44 (numerical results);
• five and more dimensions: 0.234 (numerical results);
• infinite dimensions: 0.234 (theorem for specific target distributions).

See Handbook of Markov chain Monte Carlo, chapter 4.

Of course, many proposals may not be classical random walk proposals. For example, the beta proposal on a simplex (beta) samples one new variable of the simplex from a beta distribution while rescaling all other variables. What is the dimension of this proposal? Here, the dimension is set to 2. The reason is that if the dimension of the simplex is 2, two variables are changed. If the dimension of the simplex is high, one variable is changed substantially, while all others are changed marginally.

Further, if a proposal changes a number of variables in the same way (and not independently like in a random walk proposal), the dimension of the proposal is set to the number of variables changed.

Moreover, proposals of unknown dimension are assumed to have high dimension, and the optimal acceptance rate 0.234 is used.

Finally, special proposals may have completely different desired acceptance rates. For example. the Hamiltonian Monte Carlo proposal (see Mcmc.Proposal.Hamiltonian.hmc) has a desired acceptance rate of 0.65. Specific acceptance rates can be set with PSpecial.

Constructors

PDimension Int

PDimensionUnknown

PSpecial Int Double

Provide dimension (Int) and desired acceptance rate (Double).

data PSpeed

Rough indication whether a proposal is fast or slow.

Useful during burn in. Slow proposals are not executed during fast auto tuning periods.

See BurnInSettings.

Constructors

PFast

PSlow

Instances

Eq PSpeed

Defined in Mcmc.Proposal

Methods

(==) :: PSpeed -> PSpeed -> Bool

(/=) :: PSpeed -> PSpeed -> Bool

data Proposal a

A Proposal is an instruction about how the Markov chain will traverse the state space a. Essentially, it is a probability mass or probability density conditioned on the current state (i.e., a Markov kernel).

A Proposal may be tuneable in that it contains information about how to enlarge or shrink the proposal size to decrease or increase the acceptance rate.

Predefined proposals are provided. To create custom proposals, one may use the convenience function createProposal.

Constructors

Proposal

Fields

• prName :: PName

  Name of the affected variable.

• prDescription :: PDescription

  Description of the proposal type and parameters.

• prSpeed :: PSpeed
• prDimension :: PDimension
• prWeight :: PWeight

  The weight determines how often a Proposal is executed per iteration of the Markov chain.

• prSimple :: ProposalSimple a

  Simple proposal without name, weight, and tuning information.

• prTuner :: Maybe (Tuner a)

  Tuning is disabled if set to Nothing.

Instances

Eq (Proposal a)

Defined in Mcmc.Proposal

Methods

(==) :: Proposal a -> Proposal a -> Bool

(/=) :: Proposal a -> Proposal a -> Bool

Ord (Proposal a)

Defined in Mcmc.Proposal

Methods

compare :: Proposal a -> Proposal a -> Ordering

(<) :: Proposal a -> Proposal a -> Bool

(<=) :: Proposal a -> Proposal a -> Bool

(>) :: Proposal a -> Proposal a -> Bool

(>=) :: Proposal a -> Proposal a -> Bool

max :: Proposal a -> Proposal a -> Proposal a

min :: Proposal a -> Proposal a -> Proposal a

type KernelRatio = Log Double

Ratio of the proposal kernels.

Part of the MHG acceptance ratio.

See also Jacobian.

NOTE: Actually the Jacobian should be part of the KernelRatio. However, it is more declarative to have them separate. Like so, we are constantly reminded: Is the Jacobian modifier different from 1.0?

type Jacobian = Log Double

Absolute value of the determinant of the Jacobian matrix.

Part of the MHG acceptance ratio.

See also Jacobian.

type JacobianFunction a = a -> Jacobian

Function calculating the Jacobian of a proposal.

(@~) :: Lens' b a -> Proposal a -> Proposal b infixl 7

Lift a proposal from one data type to another.

Assume the Jacobian is 1.0.

For example:

scaleFirstEntryOfTuple = _1 @~ scale

See also liftProposalWith.

liftProposal :: Lens' b a -> Proposal a -> Proposal b

See (@~).

liftProposalWith :: JacobianFunction b -> Lens' b a -> Proposal a -> Proposal b

Lift a proposal from one data type to another.

A function to calculate the Jacobian has to be provided (but see (@~)).

For further reference, please see the example Pair.

type ProposalSimple a = a -> GenIO -> IO (a, KernelRatio, Jacobian)

Simple proposal without tuning information.

Instruction about randomly moving from the current state to a new state, given some source of randomness.

In order to calculate the Metropolis-Hastings-Green ratio, we need to know the ratio of the backward to forward kernels (the KernelRatio or the probability masses or probability densities) and the Jacobian.

For unbiased proposals, these values are 1.0 such that

proposalSimpleUnbiased x g = return (x', 1.0, 1.0)

For biased proposals, the kernel ratio is qYX / qXY, where qXY is the probability density to move from X to Y, and the absolute value of the determinant of the Jacobian matrix differs from 1.0.

createProposal

Arguments

:: PDescription

Description of the proposal type and parameters.

-> (TuningParameter -> ProposalSimple a)

Function creating a simple proposal for a given tuning parameter.

-> PSpeed

Speed.

-> PDimension

Dimension.

-> PName

Name.

-> PWeight

Weight.

-> Tune

Activate tuning?

-> Proposal a

Create a proposal with a single tuning parameter.

Proposals with arbitrary tuning parameters have to be created manually. See Tuner for more information, and Hamiltonian for an example.

Tuners

data Tuner a

Required information to tune Proposals.

Constructors

Tuner

Fields

• tTuningParameter :: TuningParameter
• tTuningFunction :: TuningFunction
• tAuxiliaryTuningParameters :: AuxiliaryTuningParameters
• tAuxiliaryTuningFunction :: AuxiliaryTuningFunction a
• tGetSimpleProposal :: TuningParameter -> AuxiliaryTuningParameters -> Either String (ProposalSimple a)

  Given the tuning parameter, and the auxiliary tuning parameters, get the tuned simple proposal.

  Should return Left if the vector of auxiliary tuning parameters is invalid.

data Tune

Tune proposal?

Constructors

Tune

NoTune

Instances

Eq Tune

Defined in Mcmc.Proposal

Methods

(==) :: Tune -> Tune -> Bool

(/=) :: Tune -> Tune -> Bool

Show Tune

Defined in Mcmc.Proposal

Methods

showsPrec :: Int -> Tune -> ShowS

show :: Tune -> String

showList :: [Tune] -> ShowS

type TuningParameter = Double

Tuning parameter.

The larger the tuning parameter, the larger the proposal and the lower the expected acceptance rate; and vice versa.

type TuningFunction = AcceptanceRate -> TuningParameter -> TuningParameter

Compute new tuning parameter from a given acceptance rate and the old tuning parameter.

type AuxiliaryTuningParameters = Vector TuningParameter

Auxiliary tuning parameters; vector may be empty.

Auxiliary tuning parameters are not shown in proposal summaries.

type AuxiliaryTuningFunction a = Vector a -> AuxiliaryTuningParameters -> AuxiliaryTuningParameters

Compute new auxiliary tuning parameters from a given trace and the old auxiliary tuning parameters.

defaultTuningFunctionWith :: PDimension -> TuningFunction

Default tuning function.

Subject to change.

noTuningFunction :: TuningFunction

Do not tune.

Useful if auxiliary tuning parameters are tuned, but not the main tuning parameter.

noAuxiliaryTuningFunction :: AuxiliaryTuningFunction a

Do not tune auxiliary parameters.

tuningParameterMin :: TuningParameter

Minimal tuning parameter; subject to change.

tuningParameterMax :: TuningParameter

Maximal tuning parameter; subject to change.

tuneWithTuningParameters :: TuningParameter -> AuxiliaryTuningParameters -> Proposal a -> Either String (Proposal a)

Tune a Proposal.

The size of the proposal is proportional to the tuning parameter which has positive lower and upper boundaries of tuningParameterMin and tuningParameterMax, respectively.

Auxiliary tuning parameters may also be used by the Tuner of the proposal.

Return Left if:

• the Proposal is not tuneable;
• the auxiliary tuning parameters are invalid.

Used by fromSavedChain.

getOptimalRate :: PDimension -> Double

See PDimension.

Output

proposalHeader :: ByteString

Header of proposal summaries.

summarizeProposal :: PName -> PDescription -> PWeight -> Maybe TuningParameter -> PDimension -> Maybe (Int, Int, Double) -> ByteString

Proposal summary.