R: Place the intermediate temperatures between the temperature...

placeTempers {EMC} | R Documentation

## Place the intermediate temperatures between the temperature limits

### Description

Multiple MCMC chains based algorithms (e.g., parallel tempering, evolutionary Monte Carlo) need a temperature ladder. This function places the intermediate temperatures between the minimum and the maximum temperature for the ladder.

Below `sampDim` refers to the dimension of the sample space, `temperLadderLen` refers to the length of the temperature ladder, and `levelsSaveSampForLen` refers to the length of `levelsSaveSampFor`. Note, this function calls `evolMonteCarlo`, so some of the arguments below have the same name and meaning as the corresponding ones for `evolMonteCarlo`. See details below for explanation on the arguments.

### Usage

    placeTempers(nIters,
                 acceptRatioLimits,
                 ladderLenMax,
                 startingVals,
                 logTarDensFunc,
                 MHPropNewFunc,
                 logMHPropDensFunc = NULL,
                 temperLadder      = NULL,
                 temperLimits      = NULL,
                 ladderLen         = 15,
                 scheme            = 'exponential',
                 schemeParam       = 1.5,
                 guideMe           = TRUE,
                 levelsSaveSampFor = NULL,
                 saveFitness       = FALSE,
                 verboseLevel      = 0,
                 ...)

### Arguments

`nIters` | `integer` > 0.
`acceptRatioLimits` | `double` vector of two probabilities.
`ladderLenMax` | `integer` > 0.
`startingVals` | `double` matrix of dimension `temperLadderLen` x `sampDim` or vector of length `sampDim`, in which case the same starting values are used for every temperature level.
`logTarDensFunc` | `function` of two arguments `(draw, ...)` that returns the target density evaluated in the log scale.
`MHPropNewFunc` | `function` of four arguments `(temperature, block, currentDraw, ...)` that returns new Metropolis-Hastings proposals. See details below on the argument block.
`logMHPropDensFunc` | `function` of five arguments `(temperature, block, currentDraw, proposalDraw, ...)` that returns the proposal density evaluated in the log scale. See details below on the argument block.
`temperLadder` | `double` vector with all positive entries, in decreasing order.
`temperLimits` | `double` vector with two positive entries.
`ladderLen` | `integer` > 0.
`scheme` | `character`.
`schemeParam` | `double` > 0.
`guideMe` | `logical`.
`levelsSaveSampFor` | `integer` vector with positive entries.
`saveFitness` | `logical`.
`verboseLevel` | `integer`, a value >= 2 produces a lot of output.
`...` | optional arguments to be passed to `logTarDensFunc`, `MHPropNewFunc` and `logMHPropDensFunc`.

### Details

This function is based on the temperature placement method introduced in section 4.2 of Goswami and Liu (2007).

`acceptRatioLimits`

  This is a range for the estimated acceptance ratios for the random exchange move for the consecutive temperature levels of the final ladder. It is recommended that specified range is between 0.3 and 0.6.

`ladderLenMax`

  It is preferred that one specifies `acceptRatioLimits` for constructing the final temperature ladder. However, If one has some computational limitations then one could also specify `ladderLenMax` which will limit the length of the final temperature ladder produced. This also serves as an upper bound on the number of temperature levels while placing the intermediate temperatures using the `acceptRatioLimits`.

`temperLadder`

  This is the temperature ladder needed for the second stage preliminary run. One can either specify a temperature ladder via `temperLadder` or specify `temperLimits`, `ladderLen`, `scheme` and `schemeParam`. For details on the later set of parameters, see below. Note, `temperLadder` overrides `temperLimits`, `ladderLen`, `scheme` and `schemeParam`.

`temperLimits`

  `temperLimits = c(lowerLimit, upperLimit)` is a two-tuple of positive numbers, where the `lowerLimit` is usually 1 and `upperLimit` is a number in [100, 1000]. If stochastic optimization (via sampling) is the goal, then `lowerLimit` is taken to be in [0, 1]. Often the `upperLimit` is the maximum temperature as suggested by `findMaxTemper`.

`ladderLen`, `scheme` and `schemeParam`

  These three parameters are required (along with `temperLimits`) if `temperLadder` is not provided. We recommend taking `ladderLen` in [15, 30]. The allowed choices for `scheme` and `schemeParam` are:

`scheme` | `schemeParam`
======== | =============
linear | NA
log | NA
geometric | NA
mult-power | NA
add-power | >= 0
reciprocal | NA
exponential | >= 0
tangent | >= 0

We recommended using `scheme = 'exponential'` and `schemeParam` in [1.5, 2].

`guideMe`

  If `guideMe = TRUE`, then the function suggests different modifications to alter the setting towards a re-run, in case there are problems with the underlying MCMC run.

`levelsSaveSampFor`

  This is passed to `evolMonteCarlo` for the underlying MCMC run.

### Value

This function returns a list with the following components:

`finalLadder` | the final temperature ladder found by placing the intermediate temperatures to be used in `parallelTempering` or `evolMonteCarlo`.
`temperLadder` | the temperature ladder used for the underlying MCMC run.
`acceptRatiosEst` | the estimated acceptance ratios for the random exchange move for the consecutive temperature levels of `temperLadder`.
`CVSqWeights` | this is the square of the coefficient of variation of the weights of the importance sampling estimators used to estimate the acceptance ratios, namely, `estAcceptRatios`.
`temperLimits` | the sorted `temperLimits` argument.
`acceptRatioLimits` | the sorted `acceptRatioLimits` argument.
`nIters` | the post burn-in `nIters`.
`levelsSaveSampFor` | the `levelsSaveSampFor` argument.
`draws` | `array` of dimension `nIters` x `sampDim` x `levelsSaveSampForLen`, if `saveFitness = FALSE`. If `saveFitness = TRUE`, then the returned array is of dimension `nIters` x `(sampDim + 1)` x `levelsSaveSampForLen`; i.e., each of the `levelsSaveSampForLen` matrices contain the fitness values in their last column.
`startingVals` | the `startingVals` argument.
`time` | the time taken by the run.

### Note

The effect of leaving the default value `NULL` for some of the arguments above are as follows:

`logMHPropDensFunc` | the proposal density `MHPropNewFunc` is deemed symmetric.
`temperLadder` | valid `temperLimits`, `ladderLen`, `scheme` and `schemeParam`
| are provided, which are used to construct the `temperLadder`.
`temperLimits` | a valid `temperLadder` is provided.
`levelsSaveSampFor` | `temperLadderLen`.

### Author(s)

Gopi Goswami goswami@stat.harvard.edu

### References

Gopi Goswami and Jun S. Liu (2007). On learning strategies for evolutionary Monte Carlo. Statistics and Computing 17:1:23-38.

### See Also

`findMaxTemper`, `parallelTempering`, `evolMonteCarlo`

### Examples

    ## Not run:
    placeTempersObj <-
        with(VShapedFuncGenerator(-13579),
             placeTempers(nIters            = 10000,
                          acceptRatioLimits = c(0.5, 0.6),
                          ladderLenMax      = 50,
                          startingVals      = c(0, 0),
                          logTarDensFunc    = logTarDensFunc,
                          MHPropNewFunc     = MHPropNewFunc,
                          temperLimits      = c(1, 5),
                          ladderLen         = 10,
                          levelsSaveSampFor = seq_len(10),
                          verboseLevel      = 1))
    print(placeTempersObj)
    print(names(placeTempersObj))
    with(placeTempersObj,
     {
         par(mfcol = c(3, 3))
         for (ii in seq_along(levelsSaveSampFor)) {
             main <- paste('temper:', round(temperLadder[levelsSaveSampFor[ii]], 3))
             plot(draws[ , , ii],
                  xlim = c(-4, 20),
                  ylim = c(-8, 8),
                  pch  = '.',
                  ask  = FALSE,
                  main = as.expression(main),
                  xlab = as.expression(substitute(x[xii], list(xii = 1))),
                  ylab = as.expression(substitute(x[xii], list(xii = 2))))
         }
     })

    ## End(Not run)

[Package EMC version 1.3 Index]