fit_angmix {BAMBI}  R Documentation 
Fitting Bivariate and univariate angular mixture models
Description
Fitting Bivariate and univariate angular mixture models
Usage
fit_angmix(
model = "vmsin",
data,
ncomp,
cov.restrict = "NONE",
unimodal.component = FALSE,
start_par = NULL,
rand_start = rep(FALSE, n.chains),
method = "hmc",
perm_sampling = FALSE,
n.chains = 3,
chains_parallel = TRUE,
return_llik_contri = FALSE,
int.displ = 3,
epsilon = 0.1,
L = 10,
epsilon.random = TRUE,
L.random = FALSE,
burnin.prop = 0.5,
tune.prop = 1,
thin = 1,
propscale = 0.05,
n.iter = 500,
pmix.alpha = NULL,
norm.var = 1000,
autotune = TRUE,
show.progress = TRUE,
accpt.prob.upper,
accpt.prob.lower,
epsilon.incr = 0.05,
L.incr = 0.075,
tune.incr = 0.05,
tune_ave_size = 100,
kappa_upper = 150,
kappa_lower = 1e04,
return_tune_param = FALSE,
qrnd = NULL,
n_qrnd = NULL,
...
)
Arguments
model 
angular model whose mixtures are to be fitted. Available choices are 
data 
data matrix (if bivarate, in which case it must have two columns) or vector. If outside, the values
are transformed into the scale 
ncomp 
number of components in the mixture model. Must be a positive integer. vector values are not allowed.
If 
cov.restrict 
Should there be any restriction on the covariance parameter for a bivariate model. Available choices are

unimodal.component 
logical. Should each component in the mixture model be unimodal? Only used if 
start_par 
list with elements 
rand_start 
logical. Should a random starting clustering be used? Must be either a scalar, or a vector of length 
method 
MCMC strategy to be used for the model paramters: 
perm_sampling 
logical. Should the permutation sampling algorithm of FruhwirthSchnatter (2001) be used?
If TRUE, at every iteration after burnin, once model parameters and mixing proportions are sampled,
a random permutation of 1, ..., ncomp is considered, and components are relabelled according
to this random permutation. This forced random label switchings may imporve the mixing rate of the chage. However, (automated) tuning
is very difficult with such a scheme, as there is no simple way of keeping track of the "original" component labels. This creates problem
with computing standard deviations of the generated model parameters, thus making the
scaling step used in tuning for 
n.chains 
number of chains to run. Must be a positive integer. 
chains_parallel 
logical. Should the chains be run in parallel? Defaluts to TRUE, and ignored if 
return_llik_contri 
logical. Should the log likelihood contribution of each data point for each MCMC iteration in each chain be returned? This makes
computation of waic.angmcmc and loo.angmcmc much faster. *Warning*: Depending on the length of data and 
int.displ 
absolute integer displacement for each coordinate for 
epsilon , L 
tuning parameters for HMC; ignored if 
epsilon.random 
logical. Should 
L.random 
logical. Should a random integer between 
burnin.prop 
proportion of iterations to used for burnin. Must be a be a number in [0, 1]. Default is 0.5. 
tune.prop 
proportion of * 
thin 
thining size to be used. Must be a positive integer. If 
propscale 
tuning parameters for RWMH; a vector of size 5 (for bivariate models) or 2 (for univariate models) representing
the variances for the proposal normal densities
for the model parameters. Ignored if 
n.iter 
number of iterations for the Markov Chain. 
pmix.alpha 
concentration parameter(s) for the Dirichlet prior for 
norm.var 
variance (hyper) parameters in the normal prior for 
autotune 
logical. Should the Markov chain autotune the parameter 
show.progress 
logical. Should a progress bar be displayed? 
accpt.prob.lower , accpt.prob.upper 
lower and upper limits of acceptance ratio to be maintained while tuning
during burnin. Must be numbers between 0 and 1, which 
epsilon.incr 
amount of randomness incorporated in 
L.incr 
amount of randomness incorporated in L if 
tune.incr 
how much should the tuning parameter be increased or decreased at each step while tuning during burnin?
Must be a number between 0 and 1. See 
tune_ave_size 
number previous iterations used to compute the acceptance rate while tuning in burnin. Must be a positive integer. Defaults to 100. 
kappa_upper , kappa_lower 
upper and lower bounds for the concentration and (absolute) association parameters. Must be a positive integers. Defaults to 150 and 1e4, and parameter with value above or below these limits rarely make sense in practice. Warning: values much larger or smaller than the default are not recommended as they can cause numerical instability. 
return_tune_param 
logical. Should the values of the tuning parameters used at each iteration in each chain be returned? Defaults to 
qrnd , n_qrnd 
Used only if 
... 
Unused. 
Note
Sampling is done in log scale for the concentration parameters (kappa, kappa1 and kappa2).
Parallelization is done by default when more than one chain is used,
but the chains can be run sequentially as well by setting
chains_parallel = FALSE
. To retain reproducibility while running
multiple chains in parallel, the same RNG state is passed at the
beginning of each chain. This is done by specifying future.seed = TRUE
in future.apply::future_lapply
call. Then at the beginning of the ith
chain, before drawing any parameters, imany Uniform(0, 1) random numbers are
generated using runif(i)
(and then thrown away). This ensures that the
RNG states across chains prior to random generation of the parameters are
different, and hence, no two chains can become identical, even if they have
the same starting and tuning parameters. This, however creates a difference
between a fit_angmix
call with multiple chains which is run sequentially
by setting chains_parallel = FALSE
, and another which is run sequentially
because of a sequential plan()
(or no plan()
), with
chains_parallel = TRUE
. In the former, different RNG states are passed at
the initiation of each chain.
References
FruhwirthSchnatter, S. (2011). Label switching under model uncertainty. Mixtures: Estimation and Application, 213239.
FruhwirthSchnatter, S. (2001). Markov chain Monte Carlo estimation of classical and dynamic switching and mixture models. Journal of the American Statistical Association, 96(453), 194209.
Examples
# illustration only  more iterations needed for convergence
fit.vmsin.20 < fit_angmix("vmsin", tim8,
ncomp = 3, n.iter = 20,
n.chains = 1
)
fit.vmsin.20
# Parallelization is implemented via future_lapply from the
# package future.apply. To parallelize, first provide a parallel
# plan(); otherwise the chains will run sequentially.
# Note that not all plan() might work on every OS, as they execute
# functions defined internally in fit_mixmodel. We suggest
# plan(multisession) which works on every OS.
library(future)
library(parallel)
# plan(multisession, gc = TRUE) # parallelize chains
set.seed(1)
MC.fit < fit_angmix("vmsin", tim8,
ncomp = 3, n.iter = 5000,
n.chains = 3
)
pointest(MC.fit)
MC.fix < fix_label(MC.fit)
contour(MC.fit)
contour(MC.fix)
lpdtrace(MC.fit)