Copyright | 2021 Dominik Schrempf |
---|---|
License | GPL-3.0-or-later |
Maintainer | dominik.schrempf@gmail.com |
Stability | unstable |
Portability | portable |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Creation date: Wed May 20 13:42:53 2020.
Synopsis
- newtype PName = PName {}
- newtype PDescription = PDescription {}
- data PWeight
- pWeight :: Int -> PWeight
- data PDimension
- data PSpeed
- data Proposal a = Proposal {
- prName :: PName
- prDescription :: PDescription
- prSpeed :: PSpeed
- prDimension :: PDimension
- prWeight :: PWeight
- prFunction :: PFunction a
- prTuner :: Maybe (Tuner a)
- type KernelRatio = Log Double
- data PResult a
- = ForceAccept !a
- | ForceReject
- | Propose !a !KernelRatio !Jacobian
- type Jacobian = Log Double
- type JacobianFunction a = a -> Log Double
- type PFunction a = a -> IOGenM StdGen -> IO (PResult a, Maybe AcceptanceRates)
- createProposal :: PDescription -> (TuningParameter -> PFunction a) -> PSpeed -> PDimension -> PName -> PWeight -> Tune -> Proposal a
- data Tuner a = Tuner {}
- data Tune
- type TuningParameter = Double
- data TuningType
- type TuningFunction a = TuningType -> PDimension -> Maybe AcceptanceRate -> Maybe (Vector a) -> (TuningParameter, AuxiliaryTuningParameters) -> (TuningParameter, AuxiliaryTuningParameters)
- type AuxiliaryTuningParameters = Vector TuningParameter
- tuningFunction :: TuningFunction a
- tuningParameterMin :: TuningParameter
- tuningParameterMax :: TuningParameter
- tuneWithTuningParameters :: TuningParameter -> AuxiliaryTuningParameters -> Proposal a -> Either String (Proposal a)
- getOptimalRate :: PDimension -> Double
- (@~) :: Lens' b a -> Proposal a -> Proposal b
- liftProposal :: Lens' b a -> Proposal a -> Proposal b
- liftProposalWith :: JacobianFunction b -> Lens' b a -> Proposal a -> Proposal b
- proposalHeader :: ByteString
- summarizeProposal :: PName -> PDescription -> PWeight -> Maybe TuningParameter -> PDimension -> (Int, Int, Maybe Double, Maybe Double) -> ByteString
Proposals
Proposal name.
newtype PDescription Source #
Proposal description.
Instances
Show PDescription Source # | |
Defined in Mcmc.Proposal showsPrec :: Int -> PDescription -> ShowS # show :: PDescription -> String # showList :: [PDescription] -> ShowS # | |
Eq PDescription Source # | |
Defined in Mcmc.Proposal (==) :: PDescription -> PDescription -> Bool # (/=) :: PDescription -> PDescription -> Bool # | |
Ord PDescription Source # | |
Defined in Mcmc.Proposal compare :: PDescription -> PDescription -> Ordering # (<) :: PDescription -> PDescription -> Bool # (<=) :: PDescription -> PDescription -> Bool # (>) :: PDescription -> PDescription -> Bool # (>=) :: PDescription -> PDescription -> Bool # max :: PDescription -> PDescription -> PDescription # min :: PDescription -> PDescription -> PDescription # |
The positive weight determines how often a Proposal
is executed per
iteration of the Markov chain. Abstract data type; for construction, see
pWeight
.
pWeight :: Int -> PWeight Source #
Check if the weight is positive.
Call error
if weight is zero or negative.
data PDimension Source #
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
.
PDimension Int | |
PDimensionUnknown | |
PSpecial Int Double | Provide dimension ( |
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
.
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
.
Proposal | |
|
Instances
Eq (Proposal a) Source # | |
Ord (Proposal a) Source # | |
type KernelRatio = Log Double Source #
Ratio of the proposal kernels.
For unbiased, volume preserving proposals, the values is 1.0.
For biased proposals, the kernel ratio is qYX / qXY, where qAB is the probability density to move from A to B.
Proposal result.
ForceAccept !a | Accept the new value regardless of the prior, likelihood or Jacobian. |
ForceReject | Reject the proposal regardless of the prior, likelihood or Jacobian. |
Propose !a !KernelRatio !Jacobian | Propose a new value. In order to calculate the Metropolis-Hastings-Green ratio, we need to know
the ratio of the backward to forward kernels (the Note: The |
type PFunction a = a -> IOGenM StdGen -> IO (PResult a, Maybe AcceptanceRates) Source #
Simple proposal function without tuning information.
Instruction about randomly moving from the current state to a new state, given some source of randomness.
Maybe report acceptance rates internal to the proposal (e.g., used by proposals based on Hamiltonian dynamics).
:: PDescription | Description of the proposal type and parameters. |
-> (TuningParameter -> PFunction a) | Function creating a simple proposal function 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 auxiliary tuning parameters have to be created manually. See
Tuner
for more information, and Hamiltonian
for an example.
Tuners
Required information to tune Proposal
s.
Tuner | |
|
Tune proposal?
type TuningParameter = Double Source #
Tuning parameter.
The larger the tuning parameter, the larger the proposal and the lower the expected acceptance rate; and vice versa.
data TuningType Source #
Tuning type. To distinguish between fast and slow proposals, see
IterationMode
.
NormalTuningFastProposalsOnly | Normal tuning step with fast proposals only. |
IntermediateTuningFastProposalsOnly | Intermediate tuning step executed after each iteration with fast proposals only. Only suitable for proposals which can calculate expected acceptance rates. |
LastTuningFastProposalsOnly | The last tuning step with fast proposals only may be special. |
NormalTuningAllProposals | Normal tuning step of all proposals. |
IntermediateTuningAllProposals | Intermediate tuning step of all proposals. |
LastTuningAllProposals | The last tuning step with all proposals. |
Instances
Eq TuningType Source # | |
Defined in Mcmc.Proposal (==) :: TuningType -> TuningType -> Bool # (/=) :: TuningType -> TuningType -> Bool # |
type TuningFunction a Source #
= TuningType | |
-> PDimension | |
-> Maybe AcceptanceRate | Acceptance rate of last tuning period. May not always be available because proposals may be skipped. |
-> Maybe (Vector a) | Trace of last tuning period. Not available for intermediate tuning' steps
(see |
-> (TuningParameter, AuxiliaryTuningParameters) | |
-> (TuningParameter, AuxiliaryTuningParameters) |
Compute new tuning parameters.
type AuxiliaryTuningParameters = Vector TuningParameter Source #
Auxiliary tuning parameters.
Auxiliary tuning parameters are not shown in proposal summaries.
Vector may be empty.
tuningFunction :: TuningFunction a Source #
Default tuning function.
The default tuning function only uses the actual acceptance rate. In particular, it does not handle auxiliary tuning parameters, ignores intermediate tuning steps, and ignores the actual samples attained during the last tuning period.
tuningParameterMin :: TuningParameter Source #
Minimal tuning parameter; subject to change.
tuningParameterMax :: TuningParameter Source #
Maximal tuning parameter; subject to change.
tuneWithTuningParameters :: TuningParameter -> AuxiliaryTuningParameters -> Proposal a -> Either String (Proposal a) Source #
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 Source #
See PDimension
.
Lift proposals
(@~) :: Lens' b a -> Proposal a -> Proposal b infixl 7 Source #
Lift a proposal from one data type to another.
Assume the Jacobian is 1.0.
For example:
scaleFirstEntryOfTuple = _1 @~ scale
See also liftProposalWith
.
liftProposalWith :: JacobianFunction b -> Lens' b a -> Proposal a -> Proposal b Source #
Lift a proposal from one data type to another.
A function to calculate the Jacobian has to be provided. If the Jabobian is
1.0, use liftProposal
.
For further reference, please see the example
Pair
.
Output
proposalHeader :: ByteString Source #
Header of proposal summaries.
summarizeProposal :: PName -> PDescription -> PWeight -> Maybe TuningParameter -> PDimension -> (Int, Int, Maybe Double, Maybe Double) -> ByteString Source #
Proposal summary.