Public API¶

Functions:¶

All public functions require as a first argument a pointer to amSampler structure.

int initAMSampler(amSampler *am, int nmodels, int *model_dims,

targetDist logpost, double *initRWM);

To initialize amSampler you need to provide:

the number of models in nmodels;

the dimensions for each model in model_dims;

the logarithm of the target distribution (or posterior distribution in a Bayesian analysis) in logpost (see targetDist);

and an array with initial conditions for each model in initRWM.

initRWM is a flattened array, with the initial values in contiguous order for each model. If initRWM is passed as NULL, then the initial values are randomly selected from a uniform distribution in [0, 1).

initAMSampler allocates necessary memory for most array in the rest of the structures.

void freeAMSampler(amSampler *am);: Once you finish working with amSampler, you should free the memory with a call to freeAMSampler().

void estimate_conditional_probs(amSampler *am, int nsweeps);

Estimate the conditional probabilities of the models, to adjust for an appropriate proposal distribution. If it is not explicitely called by the user, it will be implicitely called by either burn_samples() or rjmcmc_samples() prior to drawing samples. If the call is implicit, the number of sweeps nsweeps defaults to 100,000.

In all cases, the statistics collected during the estimate_conditional_probs() calls, are stored in the cpstats member inside the amSampler struct. For a full description of cpstats, see condProbStats.

void burn_samples(amSampler *am, int nsweeps);: It is advised to burn some samples at the begining of a RJMCMC run to let the Markov chain converge.

void rjmcmc_samples(amSampler *am, int nsweeps);

This is the function that will provide the RJMCMC samples.

The statistics collected during the rjmcmc_samples() calls, are stored in the st member inside the amSampler struct. For a full description of st, see runStats.

C struct’s¶

runStats¶

Contains statistics of the rjmcmc_samples call.

naccrwmb¶: [unsigned long] Number of accepted Block-RWM.

ntryrwmb¶: [unsigned long] Number of tried Block-RWM.

naccrwms¶: [unsigned long] Number of accepted Single-RWM.

ntryrwms¶: [unsigned long] Number of tried Single-RWM.

nacctd¶: [unsigned long] Number of accepted Auto RJ.

ntrytd¶: [unsigned long] Number of tried Auto RJ.

theta_summary¶: [double ***] The theta parameter for each model, for each sweep. theta_summary[i][j][k] is the \(\theta_k\) component for the j-th sweep for the i-th model.

theta_summary_len¶: [int *] the number of sweeps for theta_summary in model k. theta_summary_len[1] = 20 means that the model 1 has 20 \(\theta\) samples.

ksummary¶: [int *] the number of times the model was visited.

amSampler¶

ch¶: A chainState instance containing the chain state of the RJMCMC.

jd¶: A proposalDist instance containing the proposal distribution for the chain.

cpstats¶: A condProbStats instance that holds statistics for the estimation of conditional probabilities (if ran).

st¶: A runStats instance that holds statistics for the RJMCMC runs (if ran).

doAdapt¶: A bool value indicating if Adaptation is to be performed or not during the RJMCMC runs. Default value is true.

doPerm¶: A bool value indicating if Permutation is to be performed or not during the RJMCMC runs. Default value is false.

student_T_dof¶: int type. The degree of freedom of the Student’s T distribution to sample from. If 0, sample from a Normal distribution instead. Default value is 0.

am_mixfit¶: A automix_mix_fit value. Default is FIGUEREIDO_MIX_FIT.

seed¶: An unsigned long value to initialize the random number generator. Defaults to clock time.

condProbStats¶

rwm_summary_len¶: TBD.

sig_k_rwm_summary¶: TBD.

nacc_ntry_rwm¶: TBD.

nfitmix¶: TBD.

fitmix_annulations¶: TBD.

fitmix_costfnnew¶: TBD.

fitmix_lpn¶: TBD.

fitmix_Lkk¶: TBD.

proposalDist¶

The proposal distribution is of the form:

\[p(\theta) = \sum_{k=1}^{k_{max}} L_k \exp \left(-\frac{1}{2} \left( \theta_k - \mu_k \right) B \cdot B^T \left( \theta_k - \mu_k \right) \right).\]

nmodels¶: The number of models in M (referred as \(K_{max}\) in thesis, p 143)

nMixComps¶: The numberof mixture components for each model (refferred as \(L_k\) in thesis, p144)

model_dims¶: The dimension of the \(\theta\) parameter space for each model.

lambda¶: The relative weights for each mixture component for each model. lambda[i][j] is the weight of the j-th mixture component for model \(M_i\).

mu¶: The mean vector for the mixture component for each model. mu[i][j][k] is the k-th vector index for the j-th mixture component for model \(M_i\).

B¶: \(B \cdot B^T\) is the covariance matrix for each mixture component for each model. B[i][j][k][m] is the k,m index of the B matrix for mixture component j of model \(M_i\).

sig¶: Vector of adapted RWM scale parameters for each model.

chainState¶

Struct to hold the MCMC chain state

theta¶: The current value of \(\theta_k\) in the chain.

pk¶: TBD.

log_posterior¶: The current value of the log-posterior.

current_model_k¶: The current model index k in the chain.

mdim¶: The dimension of the current model in the chain.

current_Lkk¶: TBD

nreinit¶: TBD.

reinit¶: TBD.

pkllim¶: TBD.

doBlockRWM¶: A bool value to indicate if the chain should do a Block-RWM. This is done every 10 sweeps.

isBurning¶: A bool that indicates wether the chain is burning samples.

sweep_i¶: The index of the chain.

Typedef’s and Enum’s¶

targetDist¶

The prototype of the log-posterior function that must be passed to amSampler upon initialization.

typedef double (*targetDist)(int model_k, double *x);

bool¶

A typedef for int. C does not have a bool type but int is just as good. true and false are also defined for compatibility with C++.

typedef int bool;
#define true 1
#define false 0

automix_mix_fit¶

Enum to specify whether using Figuereido or AutoRJ in conditional probabilities estimation.

typedef enum { FIGUEREIDO_MIX_FIT = 0, AUTORJ_MIX_FIT } automix_mix_fit;