dna_convergenceScale.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rDNA.R
\name{dna_convergenceScale}
\alias{dna_convergenceScale}
\title{Convergence diagnostics for \code{dna_scale} objects}
\usage{
dna_convergenceScale(dna_scale, variable = "both", method = "geweke",
  colors = TRUE, trace_size = 0.5, nrow = 3, ncol = 3,
  facet_page = 1, value = NULL)
}
\arguments{
\item{dna_scale}{A \code{dna_scale} object.}

\item{variable}{Variable for assessing convergence diagnostics. Can either
be the value provided in \code{variable1} or \code{variable2} of the
\code{dna_scale} functions, or \code{"both"} if both stored variables
should be analyzed. Defaults to \code{"both"}.}

\item{method}{Method for the convergence diagnostics. Supported are
\code{"geweke"}, \code{"density"} and \code{"trace"}. Defaults to
\code{"geweke"}.}

\item{colors}{Colors for either the \code{density} or \code{trace} plots.
\code{TRUE} colors the variables according to the attributes in the
object and \code{FALSE} sets colors to black. You can also provide
customized colors. Possible options are either providing a single
character vector (if you wish to color values in only one color), or a
character or numeric vector or data frame of at least the same length as
values in the object. If you use a data frame, please provide one column
named \code{"names"} that indicates the names of the values and one column
named \code{"colors"} that specifies the value colors. Defaults to
\code{TRUE}.}

\item{trace_size}{Size of the trace lines for the \code{traceplots}.}

\item{nrow}{Number of rows for the facet plot.}

\item{ncol}{Number of columns for the facet plot.}

\item{facet_page}{If the number of values to be plotted exceeds the
specified number of columns and rows of the facet plot, the plot is split
into several pages. \code{facet_page} indicates the page you wish to plot.}

\item{value}{Optional character vector if only specific values should be
analyzed. If specified, \code{variable} will be ignored.}
}
\description{
Convergence diagnostics for the MCMC chain created by the \code{dna_scale}
functions.
}
\details{
This function offers several convergence diagnostics for the MCMC chain
created by the \code{dna_scale} functions. Note that for the values
indicated in \code{variable2}, only the item discrimination parameters are
evaluated. There are three possible ways of assessing the mixing of a chain:

\code{"trace"} is a graphic inspection of the sampled values by iteration.
Once the chain has reached its stationary distribution, the parameter values
should look like a hairy caterpillar, meaning that the chain should not stay
in the same state for too long or have too many consecutive steps in one
direction.

\code{"density"} visually analyzes the cumulative density of the sampled
values for each parameter. Unimodality should indicate convergence of the
chain, while multimodality might indicate an identification problem leading
to non-convergence.

Similar to the T-Test, \code{"geweke"} conducts a difference of means test
for the sampled values for two sections of the chain, by comparing the means
of the first 10 percent of iterations with the final 50 percent of
iterations. This is done under the assumption that only the last half of
the chain has converged to the target distribution. The returned test
statistic is a standard Z-score. All values should be below the 1.96 value
which indicates significance at the p =< 0.05 level, meaning that the chain
has converged.

In case your chain has not converged, a first solution could be to increase
the \code{iterations} and the \code{burn-in} phase of your scaling. Other
options can be to reduce the scaling to only prominent actors and/or
concepts with the \code{drop_min_actors} and/or \code{drop_min_concepts}
arguments in the respective \code{dna_scale} functions. Setting
\code{constraints} or changing \code{priors} provide another possibility to
improve your results and achieve chain convergence.
}
\examples{
\dontrun{
dna_init()
conn <- dna_connection(dna_sample())
dna_scale <- dna_scale1dbin(conn,
                            variable1 = "organization",
                            variable2 = "concept",
                            qualifier = "agreement",
                            threshold = 0.51,
                            mcmc_iterations = 20000,
                            mcmc_burnin = 2000,
                            mcmc_thin = 10,
                            store_variables = "both")

dna_convergenceScale(dna_scale,
                     variable = "both",
                     method = "trace",
                     colors = TRUE,
                     nrow = 4,
                     ncol = 4)

dna_convergenceScale(dna_scale,
                     method = "density",
                     colors = TRUE,
                     nrow = 1,
                     ncol = 2,
                     value = c("Senate", "Sierra Club"))
}

}
\author{
Tim Henrichsen, Johannes B. Gruber
}