dna_scale1dord.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rDNA.R
\name{dna_scale1dord}
\alias{dna_scale1dord}
\title{One-dimensional ordinal scaling from a DNA connection.}
\usage{
dna_scale1dord(connection, variable1 = "organization",
  variable2 = "concept", qualifier = "agreement", zero_as_na = TRUE,
  threshold = NULL, lambda_constraints = NULL,
  mcmc_iterations = 20000, mcmc_burnin = 1000, mcmc_thin = 10,
  mcmc_tune = 1.5, mcmc_normalize = FALSE, lambda_start = NA,
  lambda_prior_mean = 0, lambda_prior_variance = 1,
  store_variables = "both", drop_constant_concepts = FALSE,
  drop_min_actors = 1, drop_min_concepts = 2, verbose = TRUE,
  seed = 12345, ...)
}
\arguments{
\item{connection}{A \code{dna_connection} object created by the
\link{dna_connection} function.}

\item{variable1}{The first variable for the scaling construction (see
\link{dna_network}). Defaults to \code{"organization"}.}

\item{variable2}{The second variable for the scaling construction (see
\link{dna_network}). Defaults to \code{"concept"}.}

\item{qualifier}{The qualifier variable for the scaling construction (see
\link{dna_network}). Defaults to \code{"agreement"}.}

\item{zero_as_na}{Logical. If \code{TRUE}, all non-mentions of an actor
towards a concept will be recoded as \code{NA}. If \code{FALSE} as
\code{2}.}

\item{threshold}{Numeric value that specifies when a mixed position can be
considered as agreement or disagreement. If e.g., one actor has 60 percent
of agreeing and 40 percent of disagreeing statements towards a concept, a
\code{threshold} of 0.51 will recode the actor position on this concept as
"agreement". The same accounts also for disagreeing statements. If one
actor has 60 percent of disagreeing and 40 percent of agreeing statements,
a \code{threshold} of 0.51 will recode the actor position on this concept
as "disagreement". All values in between the \code{threshold} (e.g., 55
percent agreement and 45 percent of disagreement and a threshold of 0.6)
will be recoded as \code{2}. If is set to \code{NULL}, all "mixed"
positions of actors will be recoded as \code{2}. Must be strictly
positive.}

\item{lambda_constraints}{A list of lists specifying constraints on the
concept parameters. Note that value \code{1} in the brackets of the
argument refers to the negative item difficulty parameters, which in
general should not be constrained. Value \code{2} relates to the item
discrimination parameter and should be used for constraints on concepts.
Three forms of constraints are possible:
\code{conceptname = list(2, value)} will constrain the item discrimination
parameter to be equal to the specified value (e.g., 0).
\code{conceptname = list(2,"+")} will constrain the item discrimination
parameter to be positively scaled and \code{conceptname = list(2, "-")}
will constrain the parameter to be negatively scaled (see example).}

\item{mcmc_iterations}{The number of iterations for the sampler.}

\item{mcmc_burnin}{The number of burn-in iterations for the sampler.}

\item{mcmc_thin}{The thinning interval for the sampler. Iterations must be
divisible by the thinning interval.}

\item{mcmc_tune}{The tuning parameter for the acceptance rates of the
sampler. Acceptance rates should ideally range between \code{0.15} and
\code{0.5}. Can be either a scalar or a k-vector. Must be strictly
positive.}

\item{mcmc_normalize}{Logical. Should the MCMC output be normalized? If
\code{TRUE}, samples are normalized to a mean of \code{0} and a standard
deviation of \code{1}.}

\item{lambda_start}{\code{Starting values} for the concept parameters. Can
be either a scalar or a matrix. If set to \code{NA} (default), the
\code{starting values} for the unconstrained parameters in the first
column are based on the observed response patterns. The remaining
unconstrained elements are set to starting values of either \code{1.0} or
\code{-1.0}, depending on the nature of the constraint.}

\item{lambda_prior_mean}{The prior mean of the concept parameters. Can be
either a scalar or a matrix.}

\item{lambda_prior_variance}{The prior inverse variances of the concept
parameters. Can be either a scalar or a matrix.}

\item{store_variables}{A character vector indicating which variables should
be stored from the scaling. Can either take the value of the character
vector indicated in \code{variable1} or \code{variable2} or \code{"both"}
to store both variables. Note that saving both variables can impact the
speed of the scaling. Defaults to \code{"both"}.}

\item{drop_constant_concepts}{Logical. Should concepts that have no
variation be deleted before the scaling? Defaults to \code{FALSE}.}

\item{drop_min_actors}{A numeric value specifying the minimum number of
concepts actors should have mentioned to be included in the scaling.
Defaults to \code{1}.}

\item{drop_min_concepts}{A numeric value specifying the minimum number a
concept should have been jointly mentioned by actors. Defaults to \code{2}.}

\item{verbose}{A boolean or numeric value indicating whether the iterations
of the scaling should be printed to the R console. If set to a numeric
value, every \code{verboseth} iteration will be printed. If set to
\code{TRUE}, \code{verbose} will print the total of iterations and burn-in
divided by \code{10}.}

\item{seed}{The random seed for the scaling.}

\item{...}{Additional arguments passed to \link{dna_network}. Actors can
e.g., be removed with the \code{excludeValues} arguments. The scaling can
also be applied to a specific time slice by using \code{start.date} and
\code{stop.date}.}
}
\description{
Scale ideological positions of two variables (e.g., organizations and
concepts) from a DNA connection by using Markov Chain Monte Carlo for
ordinal one-dimensional Item Response Theory. This is one of the four
scaling functions. For one-dimensional binary scaling, see
\link{dna_scale1dbin}, for two-dimensional binary scaling, see
\link{dna_scale2dbin} and for two-dimensional ordinal scaling
\link{dna_scale2dord}.
}
\details{
This function is a convenience wrapper for the
\link[MCMCpack]{MCMCordfactanal} function. Using Markov Chain Monte Carlo
(MCMC), \code{dna_scale1dord} generates a sample from the posterior
distribution of an ordinal data factor analysis model, using a
Metropolis-Hastings within Gibbs sampling algorithm. For the model form and
further help for the scaling arguments, see \link[MCMCpack]{MCMCordfactanal}.

As in a two-mode network in \link{dna_network}, two variables have to be
provided for the scaling. The first variable corresponds to the rows of a
two-mode network and usually entails actors (e.g., \code{"organizations"}),
while the second variable is equal to the columns of a two-mode network,
typically expressed by \code{"concepts"}. The \code{dna_scale} functions
use \code{"actors"} and \code{"concepts"} as synonyms for \code{variable1}
and \code{variable2}. However, the scaling is not restricted to
\code{"actors"} and \code{"concepts"} but depends on what you provide in
\code{variable1} or \code{variable2}.

\code{dna_scale1dord} internally uses the \code{combine} qualifier
aggregation and then recodes the values into \code{1} for disagreement,
\code{2} for mixed positions and \code{3} for agreement. Integer qualifiers
are not recoded. When \code{zero_is_na} is set to \code{TRUE}, non-mentions
of concepts are set to \code{NA}, while setting the argument to \code{FALSE}
recodes them to \code{2} as mixed position. By setting a \code{threshold},
you can further decide at which percentage of agreement and disagreement
an actor position on a concept can be considered as agreement/disagreement
or mixed position.

The argument \code{drop_min_actors} excludes actors with only a limited
number of concepts used. Limited participation of actors in a debate can
impact the scaling of the ideal points, as actors with only few mentions of
concepts convey limited information on their ideological position. The same
can also be done for concepts with the argument \code{drop_min_concepts}.
Concepts that have been rarely mentioned do not strongly discriminate the
ideological positions of actors and can, therefore, impact the accuracy of the
scaling. Reducing the number of actors of concepts to be scaled hence
improves the precision of the ideological positions for both variables and
the scaling itself. Another possibility to reduce the number of concepts is
to use \code{drop_constant_concepts}, which will reduce concepts not having
any variation in the agreement/disagreement structure of actors. This means
that all concepts will be dropped which have only agreeing, disagreeing or
mixed statements.

As \code{dna_scale1dord} implements a Bayesian Item Response Theory
approach, \code{priors} and \code{starting values} can be set on the concept
parameters. Changing the default \code{prior} values can often help you to
achieve better results. Constraints on the concept parameters can also be
specified to help identifying the model and to indicate in which direction
ideological positions of actors and concepts run. The scaling estimates an
item discrimination parameter and an item difficulty parameter for each
concept. We advise constraining the item discrimination parameter, as the
item difficulty parameter, in general, should not be constrained. The
returned MCMC output can also be post-processed by normalizing the samples
for each iteration with \code{mcmc_normalize}. Normalization can be a
sufficient way of identifying one-dimensional ideal point models.

To plot the resulting ideal points of actors and concepts, you can use the
\link{dna_plotScale} function. To assess if the returned MCMC chain has
converged to its stationary distribution, please use
\link{dna_convergenceScale}. The evaluation of convergence is essential to
report conclusions based on accurate parameter estimates. Achieving chain
convergence often requires setting the iterations of the MCMC chain to
several million.
}
\examples{
\dontrun{
dna_init()
conn <- dna_connection(dna_sample())
dna_scale <- dna_scale1dord(
  conn,
  variable1 = "organization",
  variable2 = "concept",
  qualifier = "agreement",
  zero_as_na = TRUE,
  threshold = 0.6,
  lambda_constraints = list(`CO2 legislation will not hurt the economy.` = list(2, "-")),
  mcmc_iterations = 20000,
  mcmc_burnin = 2000,
  mcmc_thin = 10,
  mcmc_tune = 1.5,
  mcmc_normalize = FALSE,
  lambda_prior_mean = 0,
  lambda_prior_variance = 0.1,
  store_variables = "organization",
  drop_constant_concepts = TRUE,
  verbose = TRUE,
  seed = 12345
)
}

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