{"id":15893085,"url":"https://github.com/uscbiostats/fmcmc","last_synced_at":"2025-03-20T12:33:59.154Z","repository":{"id":46291354,"uuid":"88659687","full_name":"USCbiostats/fmcmc","owner":"USCbiostats","description":"A friendly MCMC framework","archived":false,"fork":false,"pushed_at":"2023-09-18T16:00:36.000Z","size":14917,"stargazers_count":16,"open_issues_count":9,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-17T16:50:13.112Z","etag":null,"topics":["adaptive","bayesian-inference","markov-chain-monte-carlo","mcmc","metropolis-hastings","parallel-computing","r","r-package"],"latest_commit_sha":null,"homepage":"https://uscbiostats.github.io/fmcmc/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/USCbiostats.png","metadata":{"files":{"readme":"README.Rmd","changelog":"ChangeLog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-04-18T18:53:29.000Z","updated_at":"2024-06-27T22:32:08.000Z","dependencies_parsed_at":"2022-08-12T12:50:32.374Z","dependency_job_id":null,"html_url":"https://github.com/USCbiostats/fmcmc","commit_stats":{"total_commits":144,"total_committers":2,"mean_commits":72.0,"dds":0.00694444444444442,"last_synced_commit":"64249ad08b5e3b31dd8a5bfff29a3f452fb3fbf4"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/USCbiostats%2Ffmcmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/USCbiostats%2Ffmcmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/USCbiostats%2Ffmcmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/USCbiostats%2Ffmcmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/USCbiostats","download_url":"https://codeload.github.com/USCbiostats/fmcmc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244611560,"owners_count":20481217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adaptive","bayesian-inference","markov-chain-monte-carlo","mcmc","metropolis-hastings","parallel-computing","r","r-package"],"created_at":"2024-10-06T08:07:24.405Z","updated_at":"2025-03-20T12:33:58.832Z","avatar_url":"https://github.com/USCbiostats.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput:\n  github_document:\n    html_preview: false\n---\n\n```{r include=FALSE}\nknitr::opts_chunk$set(fig.path = \"man/figures/\", warning = FALSE)\n```\n\n\n# fmcmc: A friendly MCMC framework \u003cimg src=\"man/figures/logo.png\" align=\"right\" height=\"140\"/\u003e\n\n[![DOI](http://joss.theoj.org/papers/10.21105/joss.01427/status.svg)](https://doi.org/10.21105/joss.01427)\n[![R CI](https://github.com/USCbiostats/fmcmc/actions/workflows/ci.yml/badge.svg)](https://github.com/USCbiostats/fmcmc/actions/workflows/ci.yml)\n[![Build\nstatus](https://ci.appveyor.com/api/projects/status/lirawn11ssw9cq07/branch/master?svg=true)](https://ci.appveyor.com/project/gvegayon/fmcmc/branch/master)\n[![Coverage\nStatus](https://img.shields.io/codecov/c/github/USCbiostats/fmcmc/master.svg)](https://codecov.io/github/USCbiostats/fmcmc?branch=master)\n[![Lifecycle:\nstable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://www.tidyverse.org/lifecycle/#stable)\n[![CRAN\nstatus](https://www.r-pkg.org/badges/version/fmcmc)](https://cran.r-project.org/package=fmcmc)\n[![CRAN\ndownloads](http://cranlogs.r-pkg.org/badges/grand-total/fmcmc)](https://cran.r-project.org/package=fmcmc)\n[![status](https://tinyverse.netlify.com/badge/fmcmc)](https://CRAN.R-project.org/package=fmcmc)\n[![Integrative Methods of Analysis for Genetic Epidemiology](https://raw.githubusercontent.com/USCbiostats/badges/master/tommy-image-badge.svg)](https://image.usc.edu)\n \n## What\n\nThe `fmcmc` R package provides a lightweight general framework for implementing\nMarkov Chain Monte Carlo methods based on the Metropolis-Hastings algorithm. This\nimplementation's primary purpose lies in the fact that the user can incorporate the\nfollowing flexibly:\n\n1.  **Automatic convergence checker**: The algorithm splits the MCMC runs according\n    to the frequency with which it needs to check convergence. Users can\n    use either one of the included functions (`convergence_gelman,`\n    `convergence_geweke,` etc.), or provide their own.\n    \n2.  **Run multiple chains in parallel fashion**: Using either a `PSOCK` cluster\n    (default), or providing a personalized cluster object like the ones in\n    the `parallel` R package.\n\n3.  **User defined transition kernels**: Besides of canonical Gaussian Kernel,\n    users can specify their own or use one of the included in the package, for\n    example: `kernel_adapt`, `kernel_ram`, `kernel_normal_reflective`, `kernel_unif`,\n    `kernel_mirror`, or `kernel_unif_reflective`.\n    \nAll the above without requiring compiled code. For the latest about `fmcmc,` checkout\nthe [NEWS.md](NEWS.md) section.\n\n## Who is this for?\n\nWhile a lot of users rely on MCMC tools such as Stan (via the [rstan](https://cran.r-project.org/package=rstan) package) or\nWinBUGS (via [rstan](https://cran.r-project.org/package=R2WinBUGS)), in several settings either these tools are not enough\nor provide too much for things that do not need that much. So, this tool is for\nyou if:\n\n*  You have a simple model to estimate with Metropolis-Hastings.\n\n*  You want to run multiple chains of your model using out-of-the-box parallel\n   computing.\n   \n*  You don't want (or cannot) rely on external tools (so you need good-old\n   base R only for your models).\n   \n*  You want to implement a model in which your model parameters are either bounded\n   (like a standard error, for example), or are not, say, continuous (e.g., a\n   size variable in a Binomial distribution), so you need a personalized transition\n   kernel.\n   \nIn any other case, you may want to take a look at the previously mentioned R \npackages, or check out the [mcmc](https://cran.r-project.org/package=mcmc) R\npackage, which also implements the Metropolis-Hastings algorithm (although with\nnot all the features that this R package has), the [adaptMCMC](https://cran.r-project.org/package=adaptMCMC)\nR package, or the [MCMCpack](https://cran.r-project.org/package=MCMCpack) R package.\n\n# Installing\n\nIf you want to get the latest bleeding-edge version from Github, you can use [devtools](https://cran.r-project.org/package=devtools):\n\n```r\ndevtools::install_github(\"USCbiostats/fmcmc\")\n```\n\nThe latest (stable) release is also available on CRAN:\n\n```r\ninstall.packages(\"fmcmc\")\n```\n\n# Citation\n\n```{r citation, echo=FALSE, comment=\"\"}\ncitation(\"fmcmc\")\n```\n\n\n# Example: Linear regression model\n\n## First run\n\nIn the following we show how to use the package for estimating parameters in\na linear regression model. First, let's simulate some data to use:\n\n```{r random-data1}\nset.seed(78845)\nn \u003c- 1000\nX \u003c- rnorm(n)\ny \u003c- 3.0 + 2.0*X + rnorm(n, sd = 4)\n```\n\nIn this case, we have three parameters to estimate, the constant\n(2.0), the $\\beta$ coefficient (2.0), and the standard deviation parameter of the\nerror (1.5).\n\nTo estimate this model, we can either maximize the log-likelihood function--which\nis what is usually done--or we could do it using MCMC. In either case, we need\nto specify the log(unnormalized some times)-likelihood function:\n\n\n```{r ll1}\nll \u003c- function(p, X., y.) {\n  \n  joint_ll \u003c- dnorm(y. - (p[1] + X.*p[2]), sd = p[3], log = TRUE)\n  joint_ll \u003c- sum(joint_ll)\n  \n  # If is undefined, then we explicitly return infinte (instead of NaN, for\n  # example)\n  if (!is.finite(joint_ll))\n    return(-Inf)\n  \n  joint_ll\n}\n```\n\nNotice that the function has more than one argument, in this case, `p,` \nthe vector of parameters, `X.` and `y.,` the data of our model.\n\nLet's do a first run of the MCMC algorithm using the function of the same name\n(first, load the package, of course):\n\n```{r mcmc1}\nlibrary(fmcmc)\n\n# Running the MCMC (we set the seed first)\nset.seed(1215)\nans \u003c- MCMC(\n  ll,\n  initial = c(0, 0, sd(y)),\n  nsteps  = 5000,\n  X.      = X,\n  y.      = y\n  )\n```\n\nAs the output object is an object of class `mcmc` from the `coda` R package, we\ncan use all the functions from it on our output:\n\n```{r first-diagnostics}\nlibrary(coda)\nplot(ans)\nsummary(ans)\n```\n\nWhile the summary statistics look very good (we got very close to the original\nparameters), the trace of the parameters looks very bad (poor mixing). We can\nre-run the algorithm changing the scale parameter in the `kernel_normal` function.\nTo do so, we can pass `ans` as the `initial` argument so that\nthe function starts from the last point of that chain:\n\n\n```{r summary-and-plot1}\nans \u003c- MCMC(\n  ll,\n  initial = ans,\n  nsteps  = 5000,\n  X.      = X,\n  y.      = y,\n  kernel  = kernel_normal(scale = .05) # We can set the scale parameter like this\n  )\nplot(ans)\n```\n\nMuch better! Now, what if we use Vihola (2012) Robust Adaptive Metropolis (which\nis also implemented in the R package [adaptMCMC](https://cran.r-project.org/package=adaptMCMC))\n\n\n```{r summary-and-plot-ram}\nans_RAM \u003c- MCMC(\n  ll,\n  initial = ans,\n  nsteps  = 5000,\n  X.      = X,\n  y.      = y,\n  kernel  = kernel_ram() \n  )\nplot(ans_RAM)\n1 - rejectionRate(ans_RAM)\n```\n\nWe can also try using Haario et al. (2001) Adaptive Metropolis\n\n```{r summary-and-plot-adapt}\nans_AM \u003c- MCMC(\n  ll,\n  initial = ans,\n  nsteps  = 5000,\n  X.      = X,\n  y.      = y,\n  kernel  = kernel_adapt() \n  )\nplot(ans_AM)\n1 - rejectionRate(ans_AM)\n```\n\nFinally, if needed, we can also access information about the last run using `MCMC_OUTPUT`.\nFor example, if we wanted to look at the trace of the logposterior function, we could\nuse the `get_logpost()` function:\n\n```{r get_}\nplot(get_logpost(), type = \"l\")\n```\n\nThe set of proposed values is also available using the `get_draws()` function:\n\n```{r get_draws}\nboxplot(get_draws(), type = \"l\")\n```\n\nIf the previous run featured multiple chains, then `get_logpost()` would return a list\ninstead of length `get_nchains()`. \n\n## Automatic stop\n\nNow, suppose that the algorithm actually takes a lot of time to actually reach\nstationary state, then it would be nice to actually sample from the posterior\ndistribution once convergence has been reached. In the following example we \nuse multiple chains and the Gelman-Rubin diagnostic to check for convergence of the\nchain:\n\n\n```{r mcmc2}\nset.seed(1215) # Same seed as before\nans \u003c- MCMC(\n  ll,\n  initial = c(0, 0, sd(y)),\n  nsteps  = 5000,\n  X.      = X,\n  y.      = y,\n  kernel  = kernel_normal(scale = .05),\n  nchains = 2,                           # Multiple chains\n  conv_checker = convergence_gelman(200) # Checking for conv. every 200 steps\n  )\n```\n\nAs a difference from the previous case, now we didn't have to wait until the 5,000\ncompleted, but the algorithm stopped for us, allowing us to start generating\nthe desired sample much quicker.\n\n## Kernels: Making sure that we get positive values\n\nFor this final example, we will use the `kernel` argument and provide what\ncorresponds to a transition kernel which makes proposals within certain boundaries,\nin particular, we want the algorithm to propose only positive values for the `sd`\nparameter, which we now must be positive.\n\nMoreover, since we know that we will only get positive values, we\ncan go further and modify `ll` skipping the check for finite values:\n\n```{r ll2}\nll \u003c- function(p, X., y.) {\n  \n  sum(dnorm(y. - (p[1] + X.*p[2]), sd = p[3], log = TRUE))\n\n}\n```\n\nMuch simpler function! Let's do the call of the MCMC function specifying the \nright transition kernel to increase the acceptance rate. In this example, we will\nset the max of all parameters to be 5.0, and the min to be -5.0 for the constant\nand 0 for the beta coefficient and the variance parameter, all this using the\n`kernel_normal_reflective` (which implements a normal kernel with boundaries) function:\n\n```{r mcmc3}\nset.seed(1215) # Same seed as before\nans \u003c- MCMC(\n  ll,\n  initial = c(0, 0, sd(y)),\n  nsteps  = 5000,\n  X.      = X,\n  y.      = y,\n  kernel  = kernel_normal_reflective(\n    ub    = 5.0,               # All parameters have the same upper bound\n    lb    = c(-5.0, 0.0, 0.0), # But lower bound is specified per parameter\n    scale = 0.05               # This is the same scale as before\n    ),\n  nchains = 2,                           \n  conv_checker = convergence_gelman(200)\n  )\n```\n\nAgain, as the proposal kernel has lower and upper bounds, then we are guaranteed\nthat all proposed states are within the support of the parameter space.\n\n# Other tools\n\n`fmcmc` is just one way to work with Markov Chain Monte Carlo. Besides `stan` and\n`WinBUGS`, there are other ways to do MCMC in R: [mcmc](https://cran.r-project.org/package=mcmc),\n[HybridMC](https://cran.r-project.org/package=HybridMC), [adaptMCMC](https://cran.r-project.org/package=adaptMCMC), and\n[elhmc](https://cran.r-project.org/package=elhmc) among others (take a look at\nthe [CRAN Task View on Bayesian Inference](https://CRAN.R-project.org/view=Bayesian).)\n\n# Contributing to `fmcmc`\n\nWe welcome contributions to `fmcmc`. Whether reporting a bug, starting a discussion by asking a question, or proposing/requesting a new feature, please go by creating a new issue [here](https://github.com/USCbiostats/fmcmc/issues) so that we can talk about it.\n\nPlease note that the 'fmcmc' project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.\n\n\n# Funding\n\nSupported by National Cancer Institute Grant #1P01CA196596.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuscbiostats%2Ffmcmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuscbiostats%2Ffmcmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuscbiostats%2Ffmcmc/lists"}