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

Description Usage Arguments Details Value Note Author(s) References See Also Examples

View source: R/ladder.R

Description

The evolutionary Monte Carlo clustering (EMCC) algorithm needs 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 evolMonteCarloClustering, so some of the arguments below have the same name and meaning as the corresponding ones for evolMonteCarloClustering. See details below for explanation on the arguments.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
placeTempers(nIters,
             acceptRatioLimits,
             ladderLenMax,              
             startingVals,
             logTarDensFunc,
             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.

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:

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.

Gopi Goswami, Jun S. Liu and Wing H. Wong (2007). Evolutionary Monte Carlo Methods for Clustering. Journal of Computational and Graphical Statistics, 16:4:855-876.

See Also

findMaxTemper, evolMonteCarloClustering

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
## The following example is a simple stochastic optimization problem,
## the set up is same as that of findMaxTemper. Here no "heating up"
## is necessary, and hence the maximum temprature is the coldest one,
## namely, 0.5.
##
## However, we do the temperature placement to show how placeTempers
## works, assuming the maximum temperature is 5.

KMeansObj       <- KMeansFuncGenerator1(-97531)
placeTempersObj <-
    with(KMeansObj,
     {
         nLevels      <- 15
         sampDim      <- nrow(yy)
         startingVals <- sample(c(0, 1),
                                size    = nLevels * sampDim,
                                replace = TRUE)
         startingVals <- matrix(startingVals, nrow = nLevels, ncol = sampDim)
         placeTempers(nIters            = 1000,
                      acceptRatioLimits = c(0.5, 0.6),
                      ladderLenMax      = 50,
                      startingVals      = startingVals,
                      logTarDensFunc    = logTarDensFunc,
                      temperLimits      = c(0.5, 5),
                      ladderLen         = nLevels,
                      scheme            = 'geometric',
                      levelsSaveSampFor = seq_len(nLevels),
                      saveFitness       = TRUE,
                      verboseLevel      = 1)
     })
print(placeTempersObj)
print(names(placeTempersObj))
with(c(placeTempersObj, KMeansObj),
 {
     fitnessCol <- ncol(draws[ , , 1])     
     sub        <- paste('uniform prior on # of clusters: DU[',
                         priorMinClusters, ', ',
                         priorMaxClusters, ']', sep = '')
     for (ii in rev(seq_along(levelsSaveSampFor))) {
         main <- paste('EMCC (MAP) clustering (temper = ',
                       round(temperLadder[levelsSaveSampFor[ii]], 3), ')',
                       sep = '')
         MAPRow <- which.min(draws[ , fitnessCol, ii])
         clusterPlot(clusterInd        = draws[MAPRow, -fitnessCol, ii],
                     data              = yy,
                     main              = main,
                     sub               = sub,
                     knownClusterMeans = knownClusterMeans)
     }
 })
 

EMCC documentation built on May 29, 2017, 1:03 p.m.

Related to placeTempers in EMCC...