README.qmd

---
title: "README"
author: Robert Kubinec and Michal Ovádek
date: last-modified
editor: visual
page-layout: full
title-block-banner: true
---

# Introduction to R Package Idealstan

*Note: This is a beta release of `idealstan` v1.0. While most features have been implemented and are stable, there may be bugs that have not been sorted out. To report bugs with the package, please file an issue on the [Github page](https://github.com/saudiwin/idealstan/issues).*

At present, `idealstan` is only available on Github as one of its main dependencies, `cmdstanr` is also not on CRAN. To use the package, `cmdstanr` must be first be set up with a local installation of `cmdstan`, which is used for estimation. To see how to install `cmdstanr`, [see this guide](https://mc-stan.org/cmdstanr/). Note that the `cmdstanr` default installation location should be used when installing `cmdstan`.

To install this package, type the command `remotes::install_github('saudiwin/idealstan')` at the R console prompt (you first must have the `remotes` package installed from CRAN for this to work). The best way to learn how the package works is to look at the package vignettes, which can be accessed from the [package website](https://saudiwin.github.io/idealstan/), especially [Introduction to Idealstan](https://saudiwin.github.io/idealstan/vignettes/Package_Introduction.html).

**If you use this package, please cite the following:**

Kubinec, Robert. "Generalized Ideal Point Models for Robust Measurement with Dirty Data in the Social Sciences". **SocArchiv** (2024). doi:10.31219/osf.io/8j2bt.

The paper is available from [this link](https://osf.io/8j2bt/).

## About the Package

This package implements IRT (item response theory) ideal point models, which are models designed for situations in which actors make strategic choices that correlate with a unidimensional scale, such as the left-right axis in American politics. Compared to traditional IRT, ideal point models use a similar parameterization (the 2-Pl variant) but without the strong assumption that all items load in the same direction (i.e., higher ability). For more information, I refer you to [my paper](https://osf.io/8j2bt/) about IRT and ideal point models, documenting many of the features in the package.

The goal of `idealstan` is to offer both standard IRT/ideal point models and additional models for missing data, time-varying ideal points and diverse responses, such as binary, ordinal, count, continuous and positive-continuous outcomes. In addition, `idealstan` uses the Stan estimation engine to offer full Bayesian inference (with some options for approximate inference) for all models so that every model is estimated with uncertainty. Models can also have mixed outcomes, such as discrete and continuous responses.

The approach to handling missing data in this package is to model directly strategic censoring in observations. While this kind of missing data pattern can be found in many situations in which data is not missing at random, this particular version was developed to account for legislatures in which legislators (persons) are strategically absent for votes on bills (items). This approach to missing data can be usefully applied to many contexts in which a missing outcome is a function of the person's ideal point (i.e., people will tend to be present in the data when the item is far away or very close to their ideal point).

The package also includes ordinal ideal point models to handle situations in which a ranked outcome is polarizing, such as a legislator who can vote yes, no or to abstain. Because `idealstan` uses Bayesian inference, it can model any kind of ordinal data even if there aren't an even distribution of ordinal categories for each item.

The package also has extensive plotting functions via `ggplot2` for model parameters, particularly the legislator (person) ideal points (ability parameters).