Creating Surveys

Important: Ask User for Output Preference

After creating the survey, ALWAYS use AskUserQuestion to ask the user how they want the result delivered:

•Python script: Write a .py file they can import/run
•JSON file: Save the Survey to a .json or .json.gz file using survey.save("filename")
•Show code only: Display the code in the chat without creating files
•Interactive: Return the Survey object for immediate use in a session

Basic Survey Creation

python

from edsl import Survey, QuestionFreeText, QuestionMultipleChoice

# Create questions
q1 = QuestionFreeText(
    question_name="name",
    question_text="What is your name?"
)
q2 = QuestionMultipleChoice(
    question_name="color",
    question_text="What is your favorite color?",
    question_options=["Red", "Blue", "Green", "Yellow"]
)
q3 = QuestionFreeText(
    question_name="why_color",
    question_text="Why do you like that color?"
)

# Create survey from list of questions
survey = Survey([q1, q2, q3])

Adding Questions Incrementally

Survey is immutable - each operation returns a new Survey instance:

python

from edsl import Survey, QuestionFreeText

survey = Survey()

# Each add_question returns a NEW survey
survey = survey.add_question(QuestionFreeText(
    question_name="q1",
    question_text="First question?"
))

survey = survey.add_question(QuestionFreeText(
    question_name="q2",
    question_text="Second question?"
))

# Add at specific index
survey = survey.add_question(new_question, index=1)

Adding Instructions

Instructions are displayed to respondents between questions:

python

from edsl import Survey, Instruction

instruction = Instruction(
    text="Please answer the following questions honestly.",
    name="intro"  # Optional name
)

# Add instruction at the beginning
survey = survey.add_instruction(instruction, index=0)

# Add instruction between questions
survey = survey.add_instruction(
    Instruction(text="Now for some demographic questions..."),
    index=3
)

From Qualtrics QSF Files

python

from edsl import Survey

# Import from QSF file
survey = Survey.from_qsf("qualtrics_export.qsf")

# The survey will contain converted questions with:
# - Question names from DataExportTag or QID
# - Options for multiple choice questions
# - Proper question types (QuestionMultipleChoice, QuestionFreeText, etc.)

Question Types Available

python

from edsl import (
    QuestionFreeText,        # Open-ended text response
    QuestionMultipleChoice,  # Single selection from options
    QuestionCheckBox,        # Multiple selections allowed
    QuestionLinearScale,     # Numeric scale (1-5, 1-10, etc.)
    QuestionNumerical,       # Numeric answer
    QuestionYesNo,           # Yes/No question
    QuestionList,            # Return a list of items
    QuestionRank,            # Rank items in order
    QuestionMatrix,          # Grid/matrix question
)

Survey with Piping (Dynamic Text)

Reference previous answers in question text:

python

q1 = QuestionFreeText(
    question_name="name",
    question_text="What is your name?"
)
q2 = QuestionFreeText(
    question_name="greeting",
    question_text="Hello {{ name.answer }}! How are you today?"
)

survey = Survey([q1, q2])
# q2 will display the answer from q1 in its text

Chaining Operations

Survey methods can be chained since each returns a new Survey:

python

survey = (Survey([q1, q2, q3])
    .add_rule("q1", "{{ q1.answer }} == 'skip'", "q3")
    .add_skip_rule("q2", "{{ q1.answer }} == 'skip'")
    .set_full_memory_mode()
    .add_question(q4))

Quick Reference

Task	Method
Create survey	`Survey([q1, q2, q3])`
Add question	`survey.add_question(q, index=None)`
Add instruction	`survey.add_instruction(inst, index=0)`
From QSF	`Survey.from_qsf("file.qsf")`
Get question	`survey.get("question_name")`
List questions	`survey.questions`
Question names	`survey.question_names`
Number of questions	`len(survey)`