# Survey Instruments

Source: https://www.potatoannotator.com/docs/features/survey-instruments

Potato includes a library of 55 validated survey instruments for use in prestudy and poststudy phases. These instruments cover personality assessment, mental health screening, affect measurement, social attitudes, demographic batteries, and more.

## Quick Start

Use a standard instrument by specifying its ID in your config:

```yaml
phases:
  order: [consent, prestudy, annotation, poststudy]

  prestudy:
    type: prestudy
    instrument: "tipi"      # 10-item personality questionnaire

  poststudy:
    type: poststudy
    instrument: "phq-9"     # 9-item depression screening
```

## Available Instruments

### Personality (6 instruments)

| ID | Name | Items | Description |
|----|------|-------|-------------|
| `bfi-2` | Big Five Inventory-2 | 60 | Comprehensive Big Five personality assessment |
| `tipi` | Ten-Item Personality Inventory | 10 | Ultra-brief Big Five personality measure |
| `pvq-ess` | Portrait Values Questionnaire (ESS) | 21 | Human values from European Social Survey |
| `nfc` | Need for Cognition Scale | 18 | Tendency to engage in and enjoy thinking |
| `ztpi` | Zimbardo Time Perspective Inventory | 56 | Time perspective and temporal orientation |
| `gse` | General Self-Efficacy Scale | 10 | Perceived self-efficacy in coping |

### Mental Health & Well-being (12 instruments)

| ID | Name | Items | Description |
|----|------|-------|-------------|
| `phq-9` | Patient Health Questionnaire-9 | 9 | Depression screening and severity |
| `gad-7` | Generalized Anxiety Disorder-7 | 7 | Anxiety screening and severity |
| `k6` | Kessler Psychological Distress (K6) | 6 | Brief psychological distress screening |
| `k10` | Kessler Psychological Distress (K10) | 10 | Psychological distress screening |
| `ces-d` | CES Depression Scale | 20 | Depression symptoms in general population |
| `pss-10` | Perceived Stress Scale | 10 | Perception of stress in the last month |
| `brs` | Brief Resilience Scale | 6 | Ability to bounce back from stress |
| `swls` | Satisfaction With Life Scale | 5 | Global life satisfaction |
| `shs` | Subjective Happiness Scale | 4 | Global subjective happiness |
| `who-5` | WHO Well-Being Index | 5 | Positive psychological well-being |
| `ghq-12` | General Health Questionnaire-12 | 12 | Psychiatric morbidity screening |
| `sias` | Social Interaction Anxiety Scale | 20 | Anxiety in social situations |

### Affect & Emotion (2 instruments)

| ID | Name | Items | Description |
|----|------|-------|-------------|
| `panas` | Positive and Negative Affect Schedule | 20 | Positive and negative emotional states |
| `iri` | Interpersonal Reactivity Index | 28 | Multidimensional empathy measure |

### Self-Concept & Social (6 instruments)

| ID | Name | Items | Description |
|----|------|-------|-------------|
| `rse` | Rosenberg Self-Esteem Scale | 10 | Global self-esteem |
| `ucla-loneliness` | UCLA Loneliness Scale (v3) | 20 | Subjective feelings of loneliness |
| `mos-ss` | MOS Social Support Survey | 19 | Perceived social support availability |
| `macarthur-ladder` | MacArthur Subjective Social Status | 1 | Perceived social status |
| `ios` | Inclusion of Other in Self Scale | 1 | Interpersonal closeness |
| `cses` | Collective Self-Esteem Scale | 16 | Self-esteem from group memberships |

### Social/Political Attitudes (8 instruments)

| ID | Name | Items | Description |
|----|------|-------|-------------|
| `sdo-7` | Social Dominance Orientation | 16 | Preference for group-based hierarchy |
| `rwa` | Right-Wing Authoritarianism | 22 | Authoritarian attitudes |
| `mfq` | Moral Foundations Questionnaire | 30 | Moral reasoning across five foundations |
| `trust-ess` | Social Trust Scale (ESS) | 3 | Generalized social trust |
| `rotter-trust` | Interpersonal Trust Scale | 25 | Trust in others |
| `eds` | Everyday Discrimination Scale | 9 | Day-to-day discrimination experiences |
| `political-efficacy` | Political Efficacy Scale (ANES) | 4 | Belief in political influence |
| `rci-10` | Religious Commitment Inventory | 10 | Religious commitment |

### Short-Form Instruments (12 instruments)

Ultra-brief versions for time-constrained studies:

| ID | Name | Items |
|----|------|-------|
| `bfi-10` | Big Five Inventory-10 | 10 |
| `mini-ipip` | Mini-IPIP | 20 |
| `phq-2` | Patient Health Questionnaire-2 | 2 |
| `gad-2` | Generalized Anxiety Disorder-2 | 2 |
| `pss-4` | Perceived Stress Scale-4 | 4 |
| `ucla-loneliness-3` | UCLA Loneliness Scale-3 | 3 |
| `grips` | GRAT-Short (Gratitude) | 8 |
| `mfq-20` | Moral Foundations Questionnaire-20 | 20 |
| `sdo-7-short` | SDO7(s) Short Form | 8 |
| `rwa-short` | RWA Short Scale | 12 |
| `bscs` | Brief Self-Control Scale | 13 |
| `srh` | Single-Item Self-Rated Health | 1 |

### Demographic Batteries (8 instruments)

Standard demographic question sets from major surveys:

| ID | Name | Items |
|----|------|-------|
| `anes-demographics` | ANES Demographic Battery | 12 |
| `gss-demographics` | GSS Core Demographics | 14 |
| `ess-demographics` | ESS Core Demographics | 12 |
| `wvs-demographics` | WVS Demographics | 12 |
| `hrs-ses` | HRS SES Module | 14 |
| `midus-demographics` | MIDUS Core Demographics | 13 |
| `ipums-demographics` | IPUMS Harmonized Demographics | 12 |
| `acs-demographics` | ACS Demographics | 14 |

## Using Multiple Instruments

Combine multiple instruments in a single phase:

```yaml
phases:
  poststudy:
    type: poststudy
    instruments:
      - "phq-9"
      - "gad-7"
      - "pss-10"
```

## Combining with Custom Questions

Add custom questions after instrument questions:

```yaml
phases:
  poststudy:
    type: poststudy
    instrument: "panas"
    file: surveys/demographics.json
```

## Demographic Batteries

Collect standardized demographics in prestudy:

```yaml
phases:
  prestudy:
    type: prestudy
    instruments:
      - "gss-demographics"
      - "srh"
```

## Scoring

Each instrument includes scoring metadata (method, reverse items, range, interpretation cutoffs). Potato does not automatically compute scores - the metadata is provided for researchers to implement scoring logic during data analysis.

## API Reference

```python
from potato.survey_instruments import (
    get_instrument,
    get_instrument_questions,
    list_instruments,
    get_categories
)

# List all available instruments
instruments = list_instruments()

# List by category
mental_health = list_instruments(category="mental_health")

# Get full instrument definition
phq9 = get_instrument("phq-9")

# Get just the questions
questions = get_instrument_questions("tipi")
```

## Citations

Each instrument file includes full citation information. When using these instruments, please cite the original authors.

## Further Reading

- [Multi-Phase Workflows](/docs/features/surveyflow) - Setting up prestudy/poststudy phases
- [Training Phase](/docs/features/training-phase) - Annotator qualification

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/main/docs/survey_instruments.md).