---
title: "2. Data"
author: "Yuki Atsusaka and Seo-young Silvia Kim"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{2. Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

In this vignette, we show what the typical input data look like for the
`rankingQ` package using the `identity` dataset.

`rankingQ` assumes a dataset that contains (1) responses to ranking
questions with `J` items and (2) a binary indicator for whether each
respondent provides the correct answer to an anchor-ranking question, an
auxiliary ranking question whose correct answer(s) are known to
researchers. For example, the package features a dataset `identity`,
which stores real-world survey responses to a question that asks 1,082
respondents to rank four sources of identity (partisanship, race,
gender, and religion) based on their relative importance to them.

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r identity-data}
library(rankingQ)
data("identity")
```

## Target ranking question

Ranking data are expected to be in the wide format, where multiple
columns are used to represent different items and their values represent
the items' marginal ranks.

For example, in `identity`, the four sources of identity are stored in
`party`, `religion`, `gender`, and `race`.
The first respondent ranked party first, gender second, race third, and
religion fourth, so the full ranking profile `app_identity` is
`"1423"` given the reference choice set of party-religion-gender-race.

```{r main-data}
head(identity)
```

## Anchor ranking question

To perform bias correction, the data must have what we call the anchor
ranking question. The anchor question is an auxiliary ranking question
that looks similar to the target question, whose "correct" answer is
known to researchers. For example, `identity` has responses to the
anchor question that asked respondents to rank four nested units:
household, neighborhood, city, and state. These responses are included
in `household`, `neighborhood`, `city`, and `state`.
Here, the correct answer is assumed to be `"1234"`.
Based on these responses, we code an indicator variable
(`anc_correct_identity`) that takes 1 if respondents offer the correct
answer and 0 otherwise.

In the following dataset, the first and third respondents have provided
an incorrect answer for the anchor question, whereas the rest have
provided the correct answer.

```{r anchor-data}
identity[
  ,
  c("household", "neighborhood", "city", "state", "anc_correct_identity")
] |>
  tail()
```