Help for package anominate

Type:

Package

Title:

Alpha-NOMINATE Ideal Point Estimator

Version:

0.7

Date:

2024-11-21

Author:

Royce Carroll [aut], Christopher Hare [aut, cre], Jeffrey B. Lewis [aut], James Lo [aut], Keith T. Poole [aut], Howard Rosenthal [aut], Carlos Algara [aut], Samuel Fuller [aut]

Maintainer:

Christopher Hare <cdhare@ucdavis.edu>

Description:

Provides functions to estimate and interpret the alpha-NOMINATE ideal point model developed in Carroll et al. (2013, <doi:10.1111/ajps.12029>). alpha-NOMINATE extends traditional spatial voting frameworks by allowing for a mixture of Gaussian and quadratic utility functions, providing flexibility in modeling political actors' preferences. The package uses Markov Chain Monte Carlo (MCMC) methods for parameter estimation, supporting robust inference about individuals' ideological positions and the shape of their utility functions. It also contains functions to simulate data from the model and to calculate the probability of a vote passing given the ideal points of the legislators/voters and the estimated location of the choice alternatives.

License:

GPL-2

Depends:

stats, coda, wnominate, pscl, MCMCpack

URL:

https://CRAN.R-project.org/package=anominate

NeedsCompilation:

yes

Packaged:

2024-11-21 22:20:12 UTC; chare

Repository:

CRAN

Date/Publication:

2024-11-22 09:20:02 UTC

alpha-NOMINATE: Ideal Point Estimator

Description

anominate is the function that takes a rollcall object and fits the Bayesian (MCMC-based) alpha-NOMINATE model described in Carroll et al. (2013). The method estimates the structure of political actors' utility functions from roll call data with the inclusion of a separate parameter denoted as alpha. alpha values of 1 indicate normal (Gaussian) utility, while alpha values of 0 indicate quadratic utility.

Usage

anominate(rcObject, dims=1, nsamp=1000, thin=1, burnin=500, minvotes=20, 
	lop=0.025, polarity=1, random.starts=TRUE, verbose=FALSE, constrain=FALSE)

Arguments

rcObject

An object of class rollcall, from Simon Jackman's pscl package.

dims

integer, number of dimensions to estimate. Must be nonnegative and cannot exceed 10 dimensions.

nsamp

interger, total number of iterations for the sampler. nsamp divided by thin must be larger than burnin.

thin

integer, thinning interval for the MCMC samples.

burnin

integer, number of iterations to be discarded.

minvotes

integer, minimum number of votes required for a legislator to be included in the analysis.

lop

A proportion between 0 and 1, the cut-off used for excluding lopsided votes, expressed as the proportion of non-missing votes on the minority side. The default, lop=0.025, eliminates votes where the minority is smaller than 2.5 overwrites the lopsided attribute in the rollcall object inputted.

polarity

a vector specifying the legislator in the data set who is conservative on each dimension. For example, c(3,5) indicates legislator 3 is conservative on dimension 1, and legislator 5 is conservative on dimension 2. Alternatively, polarity can be specified as a string for legislator names found in legis.names (i.e., c("Bush", "Gore")) if every legislative name in the data set is unique. Finally, polarity can be specified as a list (i.e., list("cd",c(4,5))) where the first list item is a variable from the roll call object's legis.data, and the second list item is a conservative legislator on each dimension as specified by the first list item. list("cd",c(4,5)) thus specifies the legislators with congressional district numbers of 4 and 5.

random.starts

logical, indicating whether initial values for the legislator and bill parameters should be randomly drawn from a uniform distribution. If FALSE, the W-NOMINATE estimates are used as the initial values.

verbose

logical, indicates whether the progress of W-NOMINATE and alpha-NOMINATE (at each 100th iteration of the MCMC sampler) should be printed to the screen.

constrain

logical, indicates whether alpha should be constrained to equal 1 rather than estimated. This option should be used if more than one dimension is being estimated, which makes the method equivalent to a Bayesian implementation of Poole and Rosenthal's (1997) NOMINATE model.

Value

An object of class anominate, which in this documentation is also referred to as an alpha-NOMINATE object.

alpha

An object of class mcmc with the sampled values of the alpha parameter.

beta

An object of class mcmc with the sampled values of the beta parameter.

legislators

A object of class mcmc with the sampled values of the legislator ideal points, with each dimension stored in a separate list (e.g., the first dimension coordinates are stored in legislators[[1]], the second dimension coordinates in legislators[[2]], etc.).

yea.locations

A object of class mcmc with the sampled values of the Yea locations (midpoint - spread in W-NOMINATE) for each vote, with each dimension stored in a separate list (e.g., the first dimension coordinates are stored in yea.locations[[1]], the second dimension coordinates in yea.locations[[2]], etc.).

nay.locations

A object of class mcmc with the sampled values of the Nay locations (midpoint + spread in W-NOMINATE) for each vote, with each dimension stored in a separate list (e.g., the first dimension coordinates are stored in nay.locations[[1]], the second dimension coordinates in nay.locations[[2]], etc.).

wnom.result

An object of class nomObject with the W-NOMINATE (wnominate) results.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

References

Royce Carroll, Jeffrey B. Lewis, James Lo, Keith T. Poole and Howard Rosenthal. 2013. “The Structure of Utility in Spatial Models of Voting.”' American Journal of Political Science 57(4): 1008-1028.

Jeffrey B. Lewis. https://voteview.com/

Keith Poole and Howard Rosenthal. 1997. Congress: A Political-Economic History of Roll Call Voting. New York: Oxford University Press.

Examples

  data(sen111)
   
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
   nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
   verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)
  
  # Summary statistics:
  summary(sen111_anom)
  # Graphical summaries:
  plot(sen111_anom)
  densplot.anominate(sen111_anom)
  traceplot.anominate(sen111_anom)

alpha-NOMINATE Density Plot

Description

densplot.anominate reads an anominate object and plots the density of sampled values of the alpha parameter using the densplot function in coda.

Usage

  ## S3 method for class 'anominate'
densplot(x, ...)

Arguments

x

An anominate output object.

...

Other arguments to densplot.

Value

A density plot of sampled values of alpha.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  data(sen111)
  
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)
  
  summary(sen111_anom)
  densplot.anominate(sen111_anom)

alpha-NOMINATE Result for Simulated Roll Call Matrix using Normal Utility

Description

An object of class anominate that contains the estimated alpha-NOMINATE result for data simulated using normal (Gaussian) utility. Although it can easily be obtained from calling the example in simulateData, it is included here to facilitate illustration of the examples for the plot and summary functions.

Usage

data(norm_anom)

Value

An object of class anominate, which in this documentation is also referred to as an alpha-NOMINATE object.

alpha

An object of class mcmc with the sampled values of the alpha parameter.

beta

An object of class mcmc with the sampled values of the beta parameter.

legislators

yea.locations

nay.locations

wnom.result

An object of class nomObject with the W-NOMINATE (wnominate) results.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  
  normal.data <- simulateData(utility="normal") 
  norm_anom <- anominate(normal.data, dims=1, polarity=1, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'norm_anom' can be retrieved quickly with: 
  data(norm_anom)
  
  summary(norm_anom)
  plot(norm_anom)

alpha-NOMINATE Coordinate Plot

Description

plot.anominate reads an anominate object and plots the estimated ideal points.

Usage

  ## S3 method for class 'anominate'
plot(x, ...)

Arguments

x

An anominate output object.

...

Other arguments do nothing and are not passed to any functions.

Value

A coordinate plot of estimated ideal points (with 95% credible interval bars) of an anominate object.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  data(sen111)
  
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)
  
  plot(sen111_anom)

alpha-NOMINATE Result for Simulated Roll Call Matrix using Quadratic Utility

Description

An object of class anominate that contains the estimated alpha-NOMINATE result for data simulated using quadratic utility. Although it can easily be obtained from calling the example in simulateData, it is included here to facilitate illustration of the examples for the plot and summary functions.

Usage

data(quad_anom)

Value

An object of class anominate, which in this documentation is also referred to as an alpha-NOMINATE object.

alpha

An object of class mcmc with the sampled values of the alpha parameter.

beta

An object of class mcmc with the sampled values of the beta parameter.

legislators

yea.locations

nay.locations

wnom.result

An object of class nomObject with the W-NOMINATE (wnominate) results.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  
  quadrartic.data <- simulateData(utility="quadratic") 
  quad_anom <- anominate(quadrartic.data, dims=1, polarity=1, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'quad_anom' can be retrieved quickly with: 
  data(quad_anom)
  
  summary(quad_anom)
  plot(quad_anom)

111th U.S. Senate Roll Call Vote Matrix

Description

This dataframe contains a matrix of votes cast by U.S. Senators in the 111th Congress. The data are formatted consistent with the rollcall object format in Simon Jackman's pscl package.

Usage

data(sen111)

Value

The dataframe contains roll call data for all Senators in the 111th Senate. The data is formatted as a rollcall object with the following elements.

votes

data frame, containing all data from the old nom31.dat file about legislators. For a typical W-NOMINATE object run with an ORD file read using readKH, it will contain the following:

state: State name of legislator.
icpsrState: ICPSR state code of legislator.
cd: Congressional District number.
icpsrLegis: ICPSR code of legislator.
party: Party of legislator.
partyCode: ICPSR party code of legislator.

codes

list of four vectors. yea shows the codes in votes that are yea votes, 'nay' shows nay codes, notInLegis shows absences, and missing shows the missing codes.

n

numeric, number of legislators

m

numeric, number of roll calls

legis.data

data frame, containing the following information on legislators:

state: State name of legislator.
icpsrState: ICPSR state code of legislator.
cd: Congressional District number.
icpsrLegis: ICPSR code of legislator.
party: Party of legislator.
partyCode: ICPSR party code of legislator.

vote.data

null, would otherwise be a data frame containing data on the votes.

desc

null, would otherwise be a string describing the data set.

source

string, describing where data set was read from.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Source

Keith Poole. 2014. 111th Senate Roll Call Vote Data. https://www.voteview.com/.

Examples

  data(sen111)
  summary(sen111)
   
  
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)

  summary(sen111_anom)
  plot(sen111_anom)

alpha-NOMINATE Result for 111th U.S. Senate Roll Call Vote Matrix

Description

An object of class anominate that contains the estimated alpha-NOMINATE result for the 111th U.S Senate (in one dimensions). Although it can easily be obtained from calling the example in anominate, it is included here to facilitate illustration of the examples for the plot and summary functions.

Usage

data(sen111_anom)

Value

An object of class anominate, which in this documentation is also referred to as an alpha-NOMINATE object.

alpha

An object of class mcmc with the sampled values of the alpha parameter.

beta

An object of class mcmc with the sampled values of the beta parameter.

legislators

yea.locations

nay.locations

wnom.result

An object of class nomObject with the W-NOMINATE (wnominate) results.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  data(sen111)
  
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)

  summary(sen111_anom)
  plot(sen111_anom)

Simulated Roll Call Vote Matrices Generated with Normal (Gaussian) or Quadratic Utility for alpha-NOMINATE

Description

simulateData generates a matrix of roll call votes based on the assumption that legislators possess either normal (Gaussian) or quadratic utility functions. The roll call votes can then be analyzed using the alpha-NOMINATE ideal point model. The estimated value of the alpha parameter can then be compared to the known true value (1 for normal (Gaussian) utility, 0 for quadratic utility).

Usage

  simulateData(nvotes=500, nlegis=101, seed=123345, utility="normal")

Arguments

nvotes

integer, number of roll call votes ('m').

nlegis

integer, number of legislators ('n').

seed

a single value, interpreted as an integer, used to set the seed. If seed is NULL, current seed is used.

utility

String set to either “normal” or “quadratic”, specifying the utility function used to generate the roll call data.

Value

An object of class rollcall

votes

n x m roll call vote matrix in 0/1/NA format.

codes

a list with named components yea, nay, notInLegis and missing, each component a numeric vector (possibly of length 1 and possibly NA), indicating how entries in the votes component of the rollcall object should be considered. This list simply gathers up the values in the yea, nay, notInLegis and missing arguments passed to the function.

n

integer, number of legislators.

m

integer, number of roll call votes.

legis.data

matrix, user-supplied data on legislators, containing data from an ORD file. Legislator names are rownames to this matrix.

vote.data

user-supplied data on roll call votes, set to NULL.

desc

user-supplied description, set to NULL.

source

user-supplied source information, set to NULL.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  
  quadratic.data <- simulateData(utility="quadratic") 
  quad_anom <- anominate(quadratic.data, dims=1, polarity=1, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'quad_anom' can be retrieved quickly with: 
  data(quad_anom)

  summary(quad_anom)
  plot(quad_anom)

  
  normal.data <- simulateData(utility="normal") 
  norm_anom <- anominate(normal.data, dims=1, polarity=1, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'norm_anom' can be retrieved quickly with: 
  data(norm_anom)

  summary(norm_anom)
  plot(norm_anom)

alpha-NOMINATE Summary

Description

summary.anominate reads an anominate object and prints a summary.

Usage

## S3 method for class 'anominate'
summary(object, ...)

Arguments

object

An anominate output object.

...

Other arguments do nothing and are not passed to any functions.

Value

A summary of an anominate object. Reports the number of legislators, votes, dimensions, and descriptive statistics for alpha.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  data(sen111)
  
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)
  
  summary(sen111_anom)

alpha-NOMINATE Trace Plot

Description

traceplot.anominate reads an object and plots the density of sampled values of the alpha parameter using the traceplot function in coda.

Usage

  ## S3 method for class 'anominate'
traceplot(x, ...)

Arguments

x

An anominate output object.

...

Other arguments to traceplot.

Value

A trace plot of sampled values of alpha.

Author(s)

Royce Carroll rcarroll@rice.edu

Christopher Hare cdhare@ucdavis.edu

Jeffrey B. Lewis jblewis@ucla.edu

James Lo lo@uni-mannheim.de

Keith T. Poole ktpoole@uga.edu

Howard Rosenthal hl31@nyu.edu

Examples

  data(sen111)
  
  sen111_anom <- anominate(sen111, dims=1, polarity=2, 
    nsamp=200, thin=1, burnin=100, random.starts=FALSE, 
    verbose=FALSE, constrain=FALSE)
  
  # 'sen111_anom' can be retrieved quickly with: 
  data(sen111_anom)
  
  summary(sen111_anom)
  traceplot.anominate(sen111_anom)

alpha-NOMINATE: Ideal Point Estimator

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

alpha-NOMINATE Density Plot

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

alpha-NOMINATE Result for Simulated Roll Call Matrix using Normal Utility

Description

Usage

Value

Author(s)

See Also

Examples

alpha-NOMINATE Coordinate Plot

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

alpha-NOMINATE Result for Simulated Roll Call Matrix using Quadratic Utility

Description

Usage

Value

Author(s)

See Also

Examples

111th U.S. Senate Roll Call Vote Matrix

Description

Usage

Value

Author(s)

Source

See Also

Examples

alpha-NOMINATE Result for 111th U.S. Senate Roll Call Vote Matrix

Description

Usage

Value

Author(s)

See Also

Examples

Simulated Roll Call Vote Matrices Generated with Normal (Gaussian) or Quadratic Utility for alpha-NOMINATE

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

alpha-NOMINATE Summary

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

alpha-NOMINATE Trace Plot

Description

Usage

Arguments

Value

Author(s)

See Also

Examples