1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/MCMCbinaryChange.R
3\name{MCMCbinaryChange}
4\alias{MCMCbinaryChange}
5\title{Markov Chain Monte Carlo for a Binary Multiple Changepoint Model}
6\usage{
7MCMCbinaryChange(
8  data,
9  m = 1,
10  c0 = 1,
11  d0 = 1,
12  a = NULL,
13  b = NULL,
14  burnin = 10000,
15  mcmc = 10000,
16  thin = 1,
17  verbose = 0,
18  seed = NA,
19  phi.start = NA,
20  P.start = NA,
21  marginal.likelihood = c("none", "Chib95"),
22  ...
23)
24}
25\arguments{
26\item{data}{The data.}
27
28\item{m}{The number of changepoints.}
29
30\item{c0}{\eqn{c_0} is the shape1 parameter for Beta prior on
31\eqn{\phi} (the mean).}
32
33\item{d0}{\eqn{d_0} is the shape2 parameter for Beta prior on
34\eqn{\phi} (the mean).}
35
36\item{a}{\eqn{a} is the shape1 beta prior for transition
37probabilities.  By default, the expected duration is computed and
38corresponding a and b values are assigned. The expected duration
39is the sample period divided by the number of states.}
40
41\item{b}{\eqn{b} is the shape2 beta prior for transition
42probabilities.  By default, the expected duration is computed and
43corresponding a and b values are assigned. The expected duration
44is the sample period divided by the number of states.}
45
46\item{burnin}{The number of burn-in iterations for the sampler.}
47
48\item{mcmc}{The number of MCMC iterations after burn-in.}
49
50\item{thin}{The thinning interval used in the simulation.  The
51number of MCMC iterations must be divisible by this value.}
52
53\item{verbose}{A switch which determines whether or not the
54progress of the sampler is printed to the screen.  If
55\code{verbose} is greater than 0, the iteration number and the
56posterior density samples are printed to the screen every
57\code{verbose}th iteration.}
58
59\item{seed}{The seed for the random number generator.  If NA,
60current R system seed is used.}
61
62\item{phi.start}{The starting values for the mean. The default
63value of NA will use draws from the Uniform distribution.}
64
65\item{P.start}{The starting values for the transition matrix. A
66user should provide a square matrix with dimension equal to the
67number of states. By default, draws from the \code{Beta(0.9,
680.1)} are used to construct a proper transition matrix for each
69raw except the last raw.}
70
71\item{marginal.likelihood}{How should the marginal likelihood be
72calculated?  Options are: \code{none} in which case the marginal
73likelihood will not be calculated, and \code{Chib95} in which
74case the method of Chib (1995) is used.}
75
76\item{...}{further arguments to be passed}
77}
78\value{
79An mcmc object that contains the posterior sample.  This
80  object can be summarized by functions provided by the coda
81  package.  The object contains an attribute \code{prob.state}
82  storage matrix that contains the probability of \eqn{state_i} for
83  each period, and the log-marginal likelihood of the model
84  (\code{logmarglike}).
85}
86\description{
87This function generates a sample from the posterior distribution of
88a binary model with multiple changepoints. The function uses the
89Markov chain Monte Carlo method of Chib (1998).  The user supplies
90data and priors, and a sample from the posterior distribution is
91returned as an mcmc object, which can be subsequently analyzed with
92functions provided in the coda package.
93}
94\details{
95\code{MCMCbinaryChange} simulates from the posterior distribution
96of a binary model with multiple changepoints.
97
98The model takes the following form: \deqn{Y_t \sim
99\mathcal{B}ernoulli(\phi_i),\;\; i = 1, \ldots, k} Where \eqn{k}
100is the number of states.
101
102We assume Beta priors for \eqn{\phi_{i}} and for transition
103probabilities: \deqn{\phi_i \sim \mathcal{B}eta(c_0, d_0)} And:
104\deqn{p_{mm} \sim \mathcal{B}eta{a}{b},\;\; m = 1, \ldots, k} Where
105\eqn{M} is the number of states.
106}
107\examples{
108
109    \dontrun{
110    set.seed(19173)
111    true.phi<- c(0.5, 0.8, 0.4)
112
113    ## two breaks at c(80, 180)
114    y1 <- rbinom(80, 1,  true.phi[1])
115    y2 <- rbinom(100, 1, true.phi[2])
116    y3 <- rbinom(120, 1, true.phi[3])
117    y  <- as.ts(c(y1, y2, y3))
118
119    model0 <- MCMCbinaryChange(y, m=0, c0=2, d0=2, mcmc=100, burnin=100, verbose=50,
120    	      marginal.likelihood = "Chib95")
121    model1 <- MCMCbinaryChange(y, m=1, c0=2, d0=2, mcmc=100, burnin=100, verbose=50,
122    	      marginal.likelihood = "Chib95")
123    model2 <- MCMCbinaryChange(y, m=2, c0=2, d0=2, mcmc=100, burnin=100, verbose=50,
124    	      marginal.likelihood = "Chib95")
125    model3 <- MCMCbinaryChange(y, m=3, c0=2, d0=2, mcmc=100, burnin=100, verbose=50,
126    	      marginal.likelihood = "Chib95")
127    model4 <- MCMCbinaryChange(y, m=4, c0=2, d0=2, mcmc=100, burnin=100, verbose=50,
128    	      marginal.likelihood = "Chib95")
129    model5 <- MCMCbinaryChange(y, m=5, c0=2, d0=2, mcmc=100, burnin=100, verbose=50,
130    	      marginal.likelihood = "Chib95")
131
132    print(BayesFactor(model0, model1, model2, model3, model4, model5))
133
134    ## plot two plots in one screen
135    par(mfrow=c(attr(model2, "m") + 1, 1), mai=c(0.4, 0.6, 0.3, 0.05))
136    plotState(model2, legend.control = c(1, 0.6))
137    plotChangepoint(model2, verbose = TRUE, ylab="Density", start=1, overlay=TRUE)
138
139    }
140
141}
142\references{
143Jong Hee Park. 2011. ``Changepoint Analysis of Binary
144  and Ordinal Probit Models: An Application to Bank Rate Policy
145  Under the Interwar Gold Standard."
146  \emph{Political Analysis}. 19: 188-204.
147  <doi:10.1093/pan/mpr007>
148
149Andrew D. Martin, Kevin M. Quinn, and Jong Hee Park. 2011.
150``MCMCpack: Markov Chain Monte Carlo in R.'', \emph{Journal of
151Statistical Software}.  42(9): 1-21.
152\doi{10.18637/jss.v042.i09}.
153
154Siddhartha Chib. 1995. ``Marginal Likelihood from the Gibbs
155Output.''  \emph{Journal of the American Statistical
156Association}. 90: 1313-1321. <doi: 10.1080/01621459.1995.10476635>
157}
158\seealso{
159\code{\link{MCMCpoissonChange}},\code{\link{plotState}},
160  \code{\link{plotChangepoint}}
161}
162\keyword{models}
163