BoltzMM

BoltzMM: an R package for maximum pseudolikelihood estimation of fully-visible Boltzmann machines - Published in JOSS (2019)

https://github.com/andrewthomasjones/boltzmm

Scientific Fields

Repository

Boltzmann Machines with MM Algorithms

README.Rmd

---
output: github_document
---

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```




[![Downloads from the RStudio CRAN mirror](http://cranlogs.r-pkg.org/badges/BoltzMM)](https://CRAN.R-project.org/package=BoltzMM)
[![status](http://joss.theoj.org/papers/23eb189a5e0bdd2b51f668621abcc75a/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01193)



```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# BoltzMM

The BoltzMM package allows for computation of probability mass functions of fully-visible Boltzmann machines (FVBMs) via `pfvbm` and `allpfvbm`.
Random data can be generated using `rfvbm`. Maximum pseudolikelihood estimation of parameters via the MM algorithm can be conducted using `fitfvbm`.
Computation of partial derivatives and Hessians can be performed via `fvbmpartiald` and `fvbmHessian`.
Covariance estimation and normal standard errors can be computed using `fvbmcov` and `fvbmstderr`.

## Installation

If `devtools` has already been installed, then the most current build of `BoltzMM` can be obtained via the command:

```{r GH-install, eval=FALSE}
devtools::install_github('andrewthomasjones/BoltzMM',build_vignettes = TRUE)
```

The latest stable build of `BoltzMM` can be obtain from CRAN via the command:

```{r CRAN-install, eval = FALSE}
install.packages("BoltzMM", repos='http://cran.us.r-project.org')
```

An archival build of `BoltzMM` is available at http://doi.org/10.5281/zenodo.2538256. Manual installation instructions can be found within the *R* installation and administration manual https://cran.r-project.org/doc/manuals/r-release/R-admin.html.

## Examples

Compute the probability of every length n=3 binary spin vector under bvec and Mmat:

```{r example, eval = TRUE}
library(BoltzMM)
set.seed(1)

bvec <- c(0,0.5,0.25)
Mmat <- matrix(0.1,3,3) - diag(0.1,3,3)
allpfvbm(bvec,Mmat)
```

Generate num=1000 random strings of n=3 binary spin variables under bvec and Mmat.
```{r example2, eval = TRUE}
library(BoltzMM)
set.seed(1)

num <- 1000
bvec <- c(0,0.5,0.25)
Mmat <- matrix(0.1,3,3) - diag(0.1,3,3)
data <- rfvbm(num,bvec,Mmat)

head(data)
```

Fit a fully visible Boltzmann machine to data, starting from parameters bvec and Mmat.
 
```{r example3, eval = TRUE}
library(BoltzMM)
set.seed(1)

bvec <- c(0,0.5,0.25)
Mmat <- matrix(0.1,3,3) - diag(0.1,3,3)
data <- rfvbm(num,bvec,Mmat)

fitfvbm(data,bvec,Mmat)
```

Example with real data from https://hal.science/hal-01927188v1.
```{r exampleReal, eval = TRUE}
# Load bnstruct library & package
library(bnstruct)
library(BoltzMM)

# Load data
data(senate)

# Turn data into a matrix
senate_data <- as.matrix(senate)

# Recode Yes as 1, and No as -1
senate_data[senate=="Yes"] <- 1
senate_data[senate=="No"] <- -1

# Conduct imputation
imp_data <- knn.impute(suppressWarnings(matrix(as.numeric(senate_data),
                                        dim(senate_data))),
                       k=1)

# No governement - using as reference level
data_nogov <- imp_data[,-1]


# Initialize parameters
bvec <- rep(0,8)
Mmat <- matrix(0,8,8)
nullmodel<-list(bvec=bvec,Mmat=Mmat)

# Fit a fully visible Boltzmann machine to data, starting from parameters bvec and Mmat.
model <- fitfvbm(data_nogov,bvec,Mmat)
# Compute the sandwich covariance matrix using the data and the model.
covarmat <- fvbmcov(data_nogov,model,fvbmHess)
# Compute the standard errors of the parameter elements according to a normal approximation.
st_errors <- fvbmstderr(data_nogov,covarmat)
# Compute z-scores and p-values under null
test_results<-fvbmtests(data_nogov,model,nullmodel)

test_results
```

For more examples, see individual help files.

## Technical references

Please refer to the following sources regarding various facets of the FVBM models that are implemented in the package.

The FVBM model and the consistency of their maximum pseudolikelihood estimators (MPLEs) was first considered in http://doi.org/10.1162/neco.2006.18.10.2283. The MM algorithm implemented in the main function `fitfvbm` was introduced in http://doi.org/10.1162/NECO_a_00813. Here various convergence results regarding the algorithm is proved. Next, the asymptotic normality results pertaining to the use of the functions `fvbmstderr` and `fvbmtests` are proved in http://doi.org/10.1109/TNNLS.2015.2425898. Finally, the `senate` data was introduced and analysed in https://hal.science/hal-01927188v1.

## Reference to package

If you find this package useful in your work, then please follow the usual `R` instructions for citing the package in your publications. That is, follow the instructions from `citation('BoltzMM')`.

```{r citation}
# Citation instructions
citation('BoltzMM')
```

## Authorship statement

The `BoltzMM` package is co-authored by [Andrew T. Jones][], [Hien D. Nguyen][], and Jessica J. Bagnall. The initial development of the package, in native `R` was conducted by HDN. Implementation of the core loops of the package in the `C` language was performed by ATJ. JJB formatted and contributed the `senate` data set as well as the example analysis on the `senate` data. All three co-authors contributed to the documentation of the software as well as troubleshooting and testing.

[Andrew T. Jones]: https://github.com/andrewthomasjones
[Hien D. Nguyen]: https://github.com/hiendn

## Unit testing

Using the package `testthat`, we have conducted the following unit test for the GitHub build, on the date: `r format(Sys.time(), '%d %B, %Y')`. The testing files are contained in the [tests](https://github.com/andrewthomasjones/BoltzMM/tree/master/tests) folder of the repository.

## Bug reporting and contributions

Thank you for your interest in `BoltzMM`. If you happen to find any bugs in the program, then please report them on the Issues page (https://github.com/andrewthomasjones/BoltzMM/issues). Support can also be sought on this page. Furthermore, if you would like to make a contribution to the software, then please forward a pull request to the owner of the repository.

Owner

JOSS Publication

BoltzMM: an R package for maximum pseudolikelihood estimation of fully-visible Boltzmann machines

Published

February 15, 2019

DOI

10.21105/joss.01193

Volume 4, Issue 34, Page 1193

Authors

Andrew T. Jones
School of Mathematics and Physics, University of Queensland, St. Lucia 4072, Queensland Australia

Jessica J. Bagnall
Department of Mathematics and Statistics, La Trobe University, Bundoora 3086, Victoria Australia

Hien D. Nguyen
Department of Mathematics and Statistics, La Trobe University, Bundoora 3086, Victoria Australia

Editor

Yo Yehudi

Tags

artificial neural network graphical model maximum pseudolikelihood estimation multivariate binary data probability mass function

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago