Docs/Features

Survey Instruments

55 validated survey questionnaires for personality, mental health, affect, and demographics.

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

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.

Survey Instruments

Survey Instruments

Quick Start

Available Instruments

Personality (6 instruments)

Mental Health & Well-being (12 instruments)

Affect & Emotion (2 instruments)

Self-Concept & Social (6 instruments)

Social/Political Attitudes (8 instruments)

Short-Form Instruments (12 instruments)

Demographic Batteries (8 instruments)

Using Multiple Instruments

Combining with Custom Questions

Demographic Batteries

Scoring

API Reference

Citations

Further Reading