> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expectedparrot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Human studies

> Publish a survey, collect responses, and retrieve data for analysis.

Use EDSL to collect responses from people by turning a Survey into a hosted web questionnaire. Participants answer through a link; you retrieve their responses as data in Python. You can conduct a human study on its own or use the same instrument to compare human and model responses.

This example asks about an export feature. Participants who have not used it finish after the first question; those who have used it describe a problem and what would resolve it. The code first defines that questionnaire:

```python theme={null}
from edsl import QuestionYesNo, QuestionFreeText, Survey

used = QuestionYesNo(question_name="used", question_text="Have you used the export feature?")
problem = QuestionFreeText(
    question_name="problem",
    question_text="What problem, if any, did you encounter when exporting?",
)
followup = QuestionFreeText(
    question_name="followup",
    question_text="What would resolve this problem: {{ problem.answer }}?",
)
survey = (
    Survey([used, problem, followup])
    .add_stop_rule(used, "{{ used.answer }} == 'No'")
    .add_targeted_memory(followup, problem)
)
```

## Publish and collect

With [Expected Parrot login configured](https://docs.expectedparrot.com/en/latest/api_keys.md#log-in-from-a-notebook), publish it and retain the two identifiers used in the collection workflow:

```python theme={null}
info = survey.humanize(human_survey_name="Export feature feedback")
respondent_url = info["respondent_url"]
human_survey_uuid = info["uuid"]
```

`respondent_url` is the link participants open. `human_survey_uuid` identifies this hosted collection when you retrieve responses later. Calling `humanize()` creates the survey; it does not recruit participants or generate their answers. Use `survey.preview()` to inspect the questionnaire before sharing its respondent link. See [Humanize](https://docs.expectedparrot.com/en/latest/humanize.md) for presentation settings and [Prolific](https://docs.expectedparrot.com/en/latest/prolific.md) for recruitment.

## Retrieve responses

After responses have been collected:

```python theme={null}
from edsl import Coop, Results

human_results = Coop().get_human_survey_responses(human_survey_uuid)
if not isinstance(human_results, Results):
    raise TypeError("Inspect returned response data before applying Results methods.")
table = human_results.select("answer.*")
table
```

Each completed response is a row, with columns such as `answer.used`, `answer.problem`, and `answer.followup`. Participants routed past a question have no answer to it. Use `table.to_csv("human-responses.csv")` to export the selected answers, or `table.to_pandas()` for analysis in a notebook. The type check handles the service's fallback to raw response data when conversion to Results is unavailable.

To show different material to participants, attach scenarios with `survey.by(scenarios).humanize(...)` and choose an [assignment method](https://docs.expectedparrot.com/en/latest/humanize.md#scenario-list-methods). To invite a known panel, attach [respondent profiles and email addresses](https://docs.expectedparrot.com/en/latest/humanize.md#with-agent-lists-for-email-notifications). The [Human validation example](https://docs.expectedparrot.com/en/latest/research/human_validation.md) demonstrates matching human classifications with model predictions.

For adaptive interviews with human participants, use [Human interviews](https://docs.expectedparrot.com/en/latest/guides/human_interviews.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.