DREAM

See Bayesian Analysis - DREAM for information on DREAM.

minimisers.DREAM.DREAMWrapper(pars, ratInputs)

Calculate the log-likelihood for a set of parameters.

Parameters:

• pars (vector) – The current parameter values.

• ratInputs (struct) – The problem and controls to calculate log-likelihood from.

Returns:

Lik – The (natural) log-likelihood value for the given parameter values.

Return type:

float

minimisers.DREAM.runDREAM(problemStruct, controls)

Run the DREAM algorithm for a given problem and controls.

Parameters:

• problemStruct (struct) – the Project struct.

• controls (struct) – the Controls struct.

Returns:

• outProblemStruct (struct) – the output project struct.

• result (struct) – the calculation and optimisation results object.

• bayesResults (struct) – Additional Bayesian results from the algorithm.

minimisers.DREAM.functions.DREAM(dreamVariables, paramInfo, ratInputs)

Optimise a function using the Differential Evolution Adaptive Metropolis (DREAM) algorithm.

Parameters:

• dreamVariables (struct) – Algorithmic control information for DREAM.

• paramInfo (struct) – Ranges, priors and boundary handling for each parameter.

• ratInputs (struct) – Project and controls information from RAT.

Returns:

• chain (array) – The MCMC chains generated by the algorithm, with log-prior and log-likelihood values.

• output (struct) – Diagnostic information such as convergence properties, acceptance rate, CR values, etc.

• log_L (array) – Matrix of log-likelihood values sampled from chains.

minimisers.DREAM.functions.adaptPCR(DREAMPar, CR, delta_tot, lCRold)

Update the probabilities of the various crossover values.

Parameters:

• DREAMPar (struct) – Algorithmic control settings for DREAM.

• CR (vector) – The vector of crossover values.

• delta_tot (float) – The normalised Euclidean distance for each crossover value.

• lCRold (array) – The old jumping distance weights for each crossover value.

Returns:

• pCR (array) – The crossover selection probability for each parameter.

• lCR (array) – The jumping distance weights for each crossover value.

minimisers.DREAM.functions.calcLogLikelihood(x, DREAMPar, ratInputs)

Compute the log-likelihood of each d-vector of x values.

If DREAMPar.CPU > 1, runs in parallel.

Parameters:

• x (array) – The points at which to calculate likelihood and log-likelihood.

• DREAMPar (struct) – Algorithmic control information for DREAM.

• ratInputs (struct) – Project and controls information from RAT.

Returns:

log_L_x – The log-likelihood for each point in x.

Return type:

array

minimisers.DREAM.functions.calcLogPrior(x, priors)

Calculate the log-prior over a set of points.

Parameters:

• x (array) – A [nChains x nParams] array, where each row is a point in parameter space.

• priors (array) – The RAT input prior array, which is an [nParams x 5] array, where row i is the prior type, mu, sigma, min, max for parameter i.

Returns:

log_PR – An [nChains x 1] array of the log-prior for each point.

Return type:

array

minimisers.DREAM.functions.calcProposal(X, CR, DREAMPar, Table_gamma, paramInfo)

Calculate candidate points using discrete proposal distribution.

Parameters:

• X (array) – The current position of each chain.

• CR (array) – The crossover values for each parameter.

• DREAMPar (struct) – Algorithmic control information for DREAM.

• Table_gamma (array) – The DE jump length values for each parameter.

• paramInfo (struct) – Prior, bound, and boundary handling information for each parameter.

Returns:

• x_new (array) – The new points in parameter space.

• CR (array) – The new crossover values for each parameter.

minimisers.DREAM.functions.drawCR(DREAMPar, pCR)

Generate CR values based on current crossover probabilities.

Parameters:

• DREAMPar (struct) – The algorithmic control settings for DREAM.

• pCR (array) – The selection probability of crossover for each parameter.

Returns:

CR – The crossover values for each parameter.

Return type:

array

minimisers.DREAM.functions.gelman(chain, DREAMPar)

Calculate the R-statistic convergence diagnostic.

Parameters:

• chain (array) – The Markov chains from the optimisation so far.

• DREAMPar (struct) – Algorithmic control information for DREAM.

Returns:

The R-statistic convergence diagnostic for each parameter.

Return type:

R_stat

minimisers.DREAM.functions.initializeDREAM(DREAMPar, paramInfo, chain, output, log_L, ratInputs)

Initialize the starting positions of the Markov chains.

Parameters:

• DREAMPar (struct) – Algorithmic control information for DREAM.

• paramInfo (struct) – Prior, bound, and boundary handling information for each parameter.

• chain (array) – The initial chain array created by setupDREAM.

• output (struct) – The initial output struct created by setupDREAM.

• log_L (array) – The array of log-likelihood values sampled from chains.

• ratInputs (struct) – The project and controls inputs from RAT.

Returns:

• chain (array) – The initial MCMC chain array.

• output (struct) – The initial empty output struct.

• X (array) – The starting Markov chains.

• CR (array) – The crossover values for each parameter.

• pCR (array) – The selection probability of crossover for each parameter.

• lCR (array) – The jumping distance weights for each crossover value.

• delta_tot (array) – The initial normalised Euclidean distance for each crossover value.

• log_L (array) – The initial log-likelihood for each chain value.

minimisers.DREAM.functions.metropolisRule(DREAMPar, log_L_xnew, log_PR_xnew, log_L_xold, log_PR_xold)

Calculates candidate acceptance for each point using the Metropolis rule.

Parameters:

• DREAMPar (struct) – Algorithmic control information for DREAM.

• log_L_xnew (array) – The log-likelihood of the proposed new point for each chain.

• log_PR_xnew (array) – The log-prior of the proposed new point for each chain.

• log_L_xold (array) – The log-likelihood of the current newest point on the chain.

• log_PR_xold (array) – The log-prior of the current newest point on the chain.

Returns:

• accept (array) – An array of bools of whether the proposal is accepted for each parameter.

• idx_accept (array) – The parameter indices for which proposals were accepted.

minimisers.DREAM.functions.multrnd(n, p, m)

Generate a multinomial random sequence of m simulations of k outcomes with p probhabilities.

Y = MULTRND(N,P,M) generates a random sequence of m simulations of k integers from a multinomial distribution with n trials and k outcomes, where the probability for each simulation is,

\[\frac{n!}{n_1 ! n_2 ! ... n_k !} p_1^{n_1} p_2^{n_2} ... p_k^{n_k}\]

Then, a single sample {n1, n2, … , nk} have a multinomial joint distribution with parameters n and p1, p2, … , pk. The parameter n is called the number of trials; the parameters p1, p2, … , pk are called the category probabilities; k is called the number of categories.

Parameters:

• n (array) – The number of trials for each simulation.

• p (array) – The associated probability for each simulation.

• m (int) – The number of simulations.

Returns:

• X (array) – The multinomial random deviates.

• Y (array) – The multinomial probabilities of each random deviate.

Examples

>>> [X Y] = multrnd(2678, [0.1 0.06 0.7 0.14], 10)
 X =
        271         152        1873         382
        249         154        1890         385
        266         172        1862         378
        290         147        1882         359
        247         153        1873         405
        291         155        1842         390
        268         141        1900         369
        248         158        1899         373
        267         181        1855         375
        259         175        1884         360
 Y =
        0.1012    0.0568    0.6994    0.1426
        0.0930    0.0575    0.7058    0.1438
        0.0993    0.0642    0.6953    0.1412
        0.1083    0.0549    0.7028    0.1341
        0.0922    0.0571    0.6994    0.1512
        0.1087    0.0579    0.6878    0.1456
        0.1001    0.0527    0.7095    0.1378
        0.0926    0.0590    0.7091    0.1393
        0.0997    0.0676    0.6927    0.1400
        0.0967    0.0653    0.7035    0.1344

minimisers.DREAM.functions.removeOutlier(X, log_L, outlier, DREAMPar)

Find outlier chains and remove them when needed.

Parameters:

• X (array) – The current position for each chain.

• log_L (array) – The current log-likelihood for each chain.

• outlier (array) – The current array of outlier chains.

• DREAMPar (struct) – Algorithmic control information for DREAM.

Returns:

• X (array) – The position for each chain with outliers removed.

• log_L (array) – The log-likelihood for each chain with outliers removed.

• outputOutlier – The outlier array with any new removed outliers added.

minimisers.DREAM.functions.setupDREAM(DREAMPar, paramInfo)

Initialize the main variables used in DREAM.

Parameters:

• DREAMPar (struct) – Algorithmic control information for DREAM.

• paramInfo (struct) – Ranges, priors and boundary handling for each parameter.

Returns:

• outDREAMPar (struct) – The options for DREAMPar with defaults applied.

• paramInfo (struct) – The input paramInfo after range validation.

• chain (array) – The initial MCMC chain array.

• output (struct) – The initial empty output struct.

• log_L (array) – The initial array of log-likelihood values sampled from chains.

• Table_gamma (array) – The initial DE jump length values for each parameter.

• iloc (int) – The index of the current sample in the chains.

• iteration (int) – The initial iteration number.

• gen (int) – The number of new candidates generated this generation.

minimisers.DREAM.postprocessing.boundaryHandling(x, paramInfo)

Check whether parameter values remain within prior bounds, and handle ones outside.

Parameters:

• x (array) – The parameter values.

• paramInfo (struct) – Ranges, priors and boundary handling for each parameter.

minimisers.DREAM.postprocessing.calcDelta(DREAMPar, delta_tot, delta_normX, CR)

Calculate total normalised Euclidean distance for each crossover value.

Parameters:

• DREAMPar (struct) – Algorithmic control information for DREAM.

• delta_tot (array) – The initial normalised Euclidean distance for each crossover value.

• delta_normX (array) – The Euclidean distance between the new and old crossover value.

• CR (array) – The crossover values for each parameter.

Returns:

delta_tot – The updated normalised Euclidean distance for each crossover value.

Return type:

array