index.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started With [pymcmcstat](https://github.com/prmiles/pymcmcstat/wiki)\n",
    "\n",
    "Author(s): Paul Miles | Date Created: August 31, 2018\n",
    "\n",
    "# Introduction\n",
    "The [pymcmcstat](https://github.com/prmiles/pymcmcstat/wiki) package is a Python program for running Markov Chain Monte Carlo (MCMC) simulations.  Included in this package is the abilitity to use different Metropolis based sampling techniques:\n",
    "\n",
    "* Metropolis-Hastings (MH): Primary sampling method.\n",
    "* Adaptive-Metropolis (AM): Adapts covariance matrix at specified intervals.\n",
    "* Delayed-Rejection (DR): Delays rejection by sampling from a narrower distribution.  Capable of *n*-stage delayed rejection.\n",
    "* Delayed Rejection Adaptive Metropolis (DRAM): DR + AM\n",
    "\n",
    "The [pymcmcstat](https://github.com/prmiles/pymcmcstat/wiki) package is a Python implementation of the MATLAB toolbox [mcmcstat](http://helios.fmi.fi/~lainema/mcmc/).  The user interface is designed to be as similar to the MATLAB version as possible, but this implementation has taken advantage of certain data structure concepts more amenable to Python.\n",
    "\n",
    "Please see the [pymcmcstat homepage](https://github.com/prmiles/pymcmcstat/wiki) for more details about the development of this Python package.\n",
    "\n",
    "# Installation\n",
    "This code can be found on the [Github project page](https://github.com/prmiles/pymcmcstat).  The package is available on the PyPI distribution site and the latest version can be installed via,\n",
    "```python\n",
    "pip install pymcmcstat\n",
    "```\n",
    "The master branch on Github typically matches the latest release on the PyPI distribution site.  To install the master branch directly from Github,\n",
    "```python\n",
    "pip install git+https://github.com/prmiles/pymcmcstat.git\n",
    "```\n",
    "You can also clone the repository and run `python setup.py install`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#  General Examples\n",
    "There are many built-in features to [pymcmcstat](https://github.com/prmiles/pymcmcstat/wiki) that allow it to be tailored to suit your particular problem.  Below we have outlined features through a set of examples.\n",
    "\n",
    "---\n",
    "[<img src=\"images/monod_ci.png\" style=\"width: 350px; float: right;\">](Monod.ipynb)\n",
    "## [Monod](Monod.ipynb)\n",
    "Key Features:\n",
    "- Basic MCMC settings\n",
    "- Data structure initialization\n",
    "- Constructing initial parameter covariance matrix using `scipy.optimize.leastsq`.\n",
    "- Chain/Pairwise-correlation panels.\n",
    "- Credible interval generation and plotting.\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "---\n",
    "[<img src=\"images/beetle_ci.png\" style=\"width: 350px; float: right;\">](Beetle.ipynb)\n",
    "## [Beetle](Beetle.ipynb) \n",
    "Key Features:\n",
    "- Sending objects within MCMC data structure.\n",
    "- Managing objects within sum-of-squares evaluation.\n",
    "- Chain/Pairwise-correlation panels.\n",
    "- Credible interval generation and plotting.\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "---\n",
    "[<img src=\"images/banana_pairwise.png\" style=\"width: 350px; float: right;\">](Banana.ipynb)\n",
    "## [Banana](Banana.ipynb) \n",
    "Key Features:\n",
    "- Sending class objects in MCMC data structure.\n",
    "- Defining parameter covariance matrix.\n",
    "- Pairwise correlation and generation of ellipse contours.\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "---\n",
    "[<img src=\"images/algae_ci.png\" style=\"width: 550px;\" align=\"right\">](Algae.ipynb)\n",
    "## [Algae](Algae.ipynb)\n",
    "Key Features:\n",
    "- Using multiple data sets.\n",
    "- Solving system of ODE's as model response. \n",
    "- Chain/Density/Pairwise-correlation panels.\n",
    "- Generating prediction/credible intervals for multiple quantities of interest.\n",
    "\n",
    "---\n",
    "[<img src=\"images/viscoelasticity_pi.png\" style=\"width: 350px;\" align=\"right\">](Viscoelasticity.ipynb)\n",
    "## [Viscoelasticity](Viscoelasticity.ipynb)\n",
    "Key Features:\n",
    "- Loading data from `*.mat` file.\n",
    "- Calling C++ model using `ctypes` packages.\n",
    "- Specifying model parameters to be included in the sampling chain.\n",
    "- Plotting prediction/credible intervals with respect to time or deformation.\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "---\n",
    "[<img src=\"images/landau_pwc.png\" style=\"width: 350px;\" align=\"right\">](Landau_Energy.ipynb)\n",
    "## [Landau Energy](Landau_Energy.ipynb)\n",
    "Key Features:\n",
    "- Evaluating multidimensional functions (3-D polarization space).\n",
    "- Loading data from `*.mat` file.\n",
    "- Specifying model parameters to be included in the sampling chain.\n",
    "- Specifying number of observations.\n",
    "- Enhanced visualization using [mcmcplot](https://github.com/prmiles/mcmcplot).\n",
    "- Plotting prediction/credible intervals.\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "---\n",
    "[<img src=\"images/source_distribution.png\" style=\"width: 350px;\" align=\"right\">](Radiation_Source_Localization.ipynb)\n",
    "## [Radiation Source Localization](Radiation_Source_Localization.ipynb)\n",
    "Key Features:\n",
    "- Embedding user defined objects in the data structure.\n",
    "- Enhanced visualization using [mcmcplot](https://github.com/prmiles/mcmcplot).\n",
    "- Specifying model parameters to be included in the sampling chain.\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "---\n",
    "[<img src=\"images/parallel_chains.png\" style=\"width: 350px;\" align=\"right\">](Running_Parallel_Chains.ipynb)\n",
    "## [Running Parallel Chains](Running_Parallel_Chains.ipynb)\n",
    "Key Features:\n",
    "- Running multiple chains simultaneously.\n",
    "- Using Gelman-Rubin chain diagnostics.\n",
    "- Enhanced visualization using [mcmcplot](https://github.com/prmiles/mcmcplot)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "# Advanced Topics\n",
    "These tutorials address very specific features of using the package.\n",
    "\n",
    "## [Using Chain Log Files](Chain_Log_Files.ipynb)\n",
    "Key Features:\n",
    "- Saving chain logs in binary and text formats.\n",
    "- Loading log files for post processing.\n",
    "- Assessing log history to ascertain status of simulation.\n",
    "\n",
    "## [Restarting Simulations From Chain Log Files](Restarting_Simulations.ipynb)\n",
    "Key Features:\n",
    "- Saving chain logs in text format and meta data to .json.\n",
    "- Loading log files for simulation restart.\n",
    "\n",
    "## [Setting the RNG Seed](Setting_Random_Seed.ipynb)\n",
    "Key Features:\n",
    "- Set seed for random number generator within [pymcmcstat](https://github.com/prmiles/pymcmcstat/wiki).\n",
    "- Produce repeatable simulation results.\n",
    "\n",
    "## [Calling Models Written in C++](Running_Model_Using_Ctypes.ipynb)\n",
    "Key Features:\n",
    "- Call arbitrarily complex models written in other languages (e.g., C++) using the `ctypes` package.\n",
    "- Generating credible/prediction intervals using C++ based model.\n",
    "\n",
    "## [Specifying Sample Variables](Specifying_Sample_Variables.ipynb)\n",
    "Key Features:\n",
    "- Specify which model parameters should be included in sampling chain.\n",
    "\n",
    "## [Estimating Error Variance for Multiple Data Sets](Estimate_Error_Variance.ipynb)\n",
    "Key Features:\n",
    "- Setting up multiple data sets in the MCMC data structure.\n",
    "- Defining sum-of-squares function to accomodate multiple data sets.\n",
    "- Estimating a separate observation error variance for each data set.\n",
    "- Plotting prediction/credible intervals for each data set.\n",
    "\n",
    "## [Using Normal Prior Distributions](Using_Normal_Prior_Functions.ipynb)\n",
    "Key Features:\n",
    "- Enforcing normally distributed prior functions.\n",
    "- Defining non-linear parameter constraints via custom prior functions.\n",
    "\n",
    "## [Advanced Interval Plotting](Advanced_Interval_Plotting.ipynb)\n",
    "Key Features:\n",
    "- Change model, data, and interval display options when plotting credible and prediction intervals.\n",
    "- This highlights available features as of version 1.5.0."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.3"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": false,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": true,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {
    "height": "317px",
    "width": "322px"
   },
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "165px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}