Analyze MCMC convergence with R BOA package

BOA(Bayesian Output Analysis Proogram) is an R package that provides several analysis functions on generated MCMC parameters.

The paper describes its overview.

Prerequisites

You can install boa on R console:

> install.packages("boa", dependencies=TRUE)

Data load

boa assumes a sequence of generated parameters.
Typical data format is 1 column CSV each row has 1 parameter from t-step:

alpha
1.0
1.489846867585808
1.449166545632774

The first row should be the parameter name label.

If you use TUI, you can import files from “1: File” on boa.menu() listing.

> library(boa)
> boa.menu()

Bayesian Output Analysis Program (BOA)
Version 1.1.8 for x86_64, linux-gnu
Copyright (c) 2007 Brian J. Smith <[email protected]>

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License or any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

For a copy of the GNU General Public License write to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA  02111-1307, USA, or visit their web site at
http://www.gnu.org/copyleft/gpl.html

NOTE: if the event of a menu system crash, type
"boa.menu(recover = TRUE)" to restart and recover your work.

BOA MAIN MENU
*************

1: File            >>
2: Data Management >>
3: Analysis        >>
4: Plot            >>
5: Options         >>
6: Window          >>

Selection:

At first, you may need to set the working directory from “1: File > 3: Import Data > 7: Options… > 1) Working Directory”.
For the current directory, just specify ..

Go to “1: File > 3: Import Data > 4: Flat ASCII Files” to load a file. It automatically add suffix ‘.txt’, so you need to specify the file name without suffix.
You can load 1 file at a time, but multiple files can be stored into the working chain through repetitive import operations.

If you don’t use boa.menu(), boa.importASCII() loads data directory from text file:

> library(boa)
> link<-boa.importASCII("mcmc-params.txt", ".")

Analyze

“3: Analysis > 4: Convergence Diagnostics” on boa.menu() lists its main tools.
Metrics is introduced in the paper briefly.

“Raftery and Lewis” analysis provides several tuning hints.
- Burn-in & Thin will be proposed.
- Dependence Factor with under 5.x criterion can be used to determine if parameters get converged.
“Geweke” analysis provides stable convergence metrics.
- With under Z-value 1.96, you can simply judge convergence.

When you want to call functions without boa.menu(), it provides several functions like boa.gandr(), boa.randl(), boa.geweke() and so on.
You can consult the reference on its interface.

For example, randl() means “Raftery and Lewis” way which implicitly refers to their article “How Many Iterations in the Gibbs Sampler?”.

> boa.randl(link, q=0.975, error=0.005, prob=0.95, delta=0.001)
      Thin Burn-in Total Lower Bound Dependence Factor
alpha 1      14 15558        3746           4.15323

Detailed usage depends on each way, so suitable parameters or output evaluation should be taken on each article.

Plot

“4: Plot > 3: Descriptive” has basic graph plotting tools.
“4: Density” is very useful as posterior distribution is mostly unknown on a parameter tuning phase.

⁋ Feb 15, 2023↻ Nov 7, 2024