Humanize

This page covers code methods for launching surveys, gathering human responses, and analyzing results. For interactive survey building, see Survey Builder. For Prolific recruitment, see Prolific studies. For email notifications and scheduled reminders, see Survey notifications.

How it works

Create Surveys with desired types of Questions.

Humanize the survey to generate a web-hosted version on Expected Parrot with a respondent link and an admin dashboard.

Share the respondent link with human participants (or recruit via Prolific).

Collect responses back as a standard EDSL Results object.

Analyze your human results alongside any LLM results.

Basic usage

from edsl import Survey, QuestionMultipleChoice, QuestionFreeText, QuestionLinearScale

q1 = QuestionMultipleChoice(
    question_name="frequency",
    question_text="How often do you work from home?",
    question_options=["Never", "1-2 days a week", "3-4 days a week", "Every day"],
)
q2 = QuestionLinearScale(
    question_name="satisfaction",
    question_text="How satisfied are you with your current work arrangement?",
    question_options=[1, 2, 3, 4, 5],
    option_labels={1: "Very dissatisfied", 5: "Very satisfied"},
)
q3 = QuestionFreeText(
    question_name="improvement",
    question_text="What one change would most improve your day-to-day work experience?",
)

survey = Survey([q1, q2, q3])

info = survey.humanize(
    human_survey_name="Workplace Experience Survey",
    survey_description="A short survey about remote and in-office work preferences.",
    survey_visibility="unlisted",
)

print(info["respondent_url"])  # share with respondents
print(info["admin_url"])       # monitor responses
print(info["uuid"])            # save this to retrieve results later

`.humanize()` parameters

Parameter	Type	Default	Description
`human_survey_name`	str	`"New survey"`	Display name on Coop
`survey_description`	str \| None	None	Optional description
`survey_alias`	str \| None	None	URL-friendly alias
`survey_visibility`	str	`"private"`	`"private"`, `"public"`, or `"unlisted"`
`humanize_schema`	dict \| None	None	Controls question styling and optionality — see Humanize schema
`delivery_map`	DeliveryMap \| None	None	Maps delivery channels to agent trait columns; required for email notifications

Return value

survey.humanize() returns a Scenario (dict-like) with these keys:

Key	Description
`uuid`	Human survey UUID — needed to fetch responses later
`respondent_url`	Public link for respondents
`admin_url`	Admin dashboard link
`name`	Survey name
`n_responses`	Response count (0 at creation)
`survey_uuid`	UUID of the pushed survey object
`scenario_list_uuid`	UUID of the pushed scenario list (if any)

Save the uuid — you need it to retrieve responses.

Previewing before deployment

Use .preview() to get a preview URL without creating a live survey:

preview_url = survey.preview()
print(preview_url)

# With schema customization
preview_url = survey.preview(humanize_schema=schema)

With scenarios

When using scenarios, call .humanize() on a Jobs object (not directly on the survey). You must specify a scenario_list_method. This example shows each respondent a different policy description and asks for their reaction:

from edsl import Survey, QuestionFreeText, QuestionLinearScale, Scenario, ScenarioList

scenarios = ScenarioList([
    Scenario({"policy": "Four-day workweek with no change in pay"}),
    Scenario({"policy": "Flexible start times between 7am and 11am"}),
    Scenario({"policy": "Monthly remote-work stipend of $100"}),
])

q1 = QuestionLinearScale(
    question_name="support",
    question_text="How much do you support this policy: '{{ scenario.policy }}'?",
    question_options=[1, 2, 3, 4, 5],
    option_labels={1: "Strongly oppose", 5: "Strongly support"},
)
q2 = QuestionFreeText(
    question_name="reasoning",
    question_text="What is the main reason for your rating?",
)

survey = Survey([q1, q2])

info = survey.by(scenarios).humanize(
    human_survey_name="Workplace Policy Reactions",
    scenario_list_method="randomize",
)

Scenario list methods

Method	Behavior
`"randomize"`	Each respondent gets a random scenario (with replacement)
`"ordered"`	Scenarios are assigned sequentially to respondents
`"loop"`	Survey is expanded — every question is repeated for every scenario
`"single_scenario"`	Exactly one scenario is used for all respondents (list must have length 1)

Rules:

If you attach scenarios, you must specify scenario_list_method.
If you specify a method, you must attach scenarios.
Agents and models are not supported with humanize — the survey goes to real humans.

With agent lists (for email notifications)

Attach an AgentList via .by() to associate respondents with email addresses. Pass a DeliveryMap to tell Coop which agent trait holds the email address.

from edsl import Survey, Agent, AgentList
from edsl.coop.coop_humanize_notifications import ChannelConfig, DeliveryMap

agents = AgentList([
    Agent(traits={"name": "Jordan", "email": "[email protected]"}),
    Agent(traits={"name": "Taylor", "email": "[email protected]"}),
    Agent(traits={"name": "Morgan", "email": "[email protected]"}),
])

info = survey.by(agents).humanize(
    human_survey_name="Panel Study — Wave 1",
    agent_list_description="Recruited panel participants",
    delivery_map=DeliveryMap(email=ChannelConfig(col_name="email")),
)

col_name must match the trait key that holds each respondent’s email address. Once deployed, use Survey notifications to send invitations, schedule reminders, and track delivery status.

Retrieving responses

from edsl import Coop

coop = Coop()

results = coop.get_human_survey_responses("your-human-survey-uuid")
results.select("answer.frequency", "answer.satisfaction", "answer.improvement").print()

Checking response count

status = coop.get_human_survey("your-human-survey-uuid")
print(f"Responses received: {status['n_responses']}")

Working with file upload responses

If your survey includes a QuestionFileUpload question, each response’s answer for that question is a list of file-info dicts. Use FileStore.from_file_upload_answer (single file) or FileStoreList.from_file_upload_answers (all files at once) to download and wrap them:

from edsl import Coop
from edsl.scenarios import FileStore, FileStoreList

coop = Coop()

results = coop.get_human_survey_responses("your-human-survey-uuid")

# Each answer is a list of uploaded file dicts
uploaded_files = results[0]["answer"]["my_upload_question"]

# Download all files as a FileStoreList
fsl = FileStoreList.from_file_upload_answers(uploaded_files)

# Or download a single file
fs = FileStore.from_file_upload_answer(uploaded_files[0])

The returned FileStore and FileStoreList objects behave like any other — you can inspect, filter, or pass them into further EDSL workflows.

QR code

Generate a QR code for the respondent link using get_human_survey_qr_code(). Requires the qrcode library (pip install "edsl[full]" or pip install "qrcode[pil]").

from edsl import Coop

coop = Coop()

qr = coop.get_human_survey_qr_code("your-human-survey-uuid")
qr.save("qr_code.png")  # save to file

Prolific integration

For paid recruitment via Prolific, see the Prolific studies page. The short version:

from edsl import Coop

coop = Coop()

info = survey.humanize(human_survey_name="Workplace Experience Survey")

study = coop.create_prolific_study(
    human_survey_uuid=info["uuid"],
    name="Workplace Experience Study",
    description="A short survey about remote and in-office work preferences. Takes about 3 minutes.",
    num_participants=200,
    estimated_completion_time_minutes=3,
    participant_payment_cents=75,
)

# create_prolific_study leaves the study in DRAFT mode — publish to make it live
coop.publish_prolific_study(human_survey_uuid=info["uuid"])

Introduction

Getting Started

Core Concepts

Getting Data

Working with Results

Validating with Humans

No-code Apps

Platform

How-to Guides

Notebook Examples

Developers

How it works

Basic usage

`.humanize()` parameters

Return value

Previewing before deployment

With scenarios

Scenario list methods

With agent lists (for email notifications)

Retrieving responses

Checking response count

Working with file upload responses

QR code

Prolific integration

​How it works

​Basic usage

​.humanize() parameters

​Return value

​Previewing before deployment

​With scenarios

​Scenario list methods

​With agent lists (for email notifications)

​Retrieving responses

​Checking response count

​Working with file upload responses

​QR code

​Prolific integration

How it works

Basic usage

`.humanize()` parameters

Return value

Previewing before deployment

With scenarios

Scenario list methods

With agent lists (for email notifications)

Retrieving responses

Checking response count

Working with file upload responses

QR code

Prolific integration