Loading and understanding the dataset

Concept

Before we analyze anything, we need to know what we have. That means the shape of the data, what a single row represents, how the separate files relate to one another, and what task produced them. Skipping this step is how an analysis ends up answering a question the data can't actually support. It is also the step most easily skipped, because plausible output can be produced regardless of whether anyone has understood the data first.

The task that produced this data is the one you built in the first half of the course. A participant saw three moving circles and clicked them for points across three timed phases. One circle (labeled R1) earned points in phase 1. A second circle (R2) earned points in phase 2. A third circle (the distractor) never earned points. Phase 3 offered no points for clicking any circle. Phases 1 and 2 lasted two minutes each and phase 3 lasted one minute, so a complete session runs about five minutes.

A note on the data

The dataset here is simulated. We ran the real task on a few pilot participants, whose data is kept separately in data/pilot/, but three people are too few to demonstrate a group-level analysis. So we generated a cohort of 40 participants (data/synthetic/) whose behavior was built to match the real task. We did this so the workshop can show both the single-subject analysis common in behavior analysis and the group-level analysis other fields expect. We also built it to show the kinds of quality problems that real online data contains. Everything here is simulated unless we say otherwise.

The three files

The study stored its data in three tables, exported here as three CSV files.

Ask Claude:

Load participants.csv, demographics.csv, and responses.csv from data/synthetic/.
For each, print its shape and its column names.

What comes back:

participants   (40, 7)   id, prolificId, createdAt, consented, comprehensionAttempts,
                         instructionsCompleted, taskCompleted
demographics   (40, 6)   id, participantId, age, gender, education, submittedAt
responses    (11799, 6)  id, participantId, phase, button, reinforced, respondedAt

Reading the output: the shape is (rows, columns). There are 40 participants, a comparable number of demographics records, and nearly twelve thousand response rows. That last number is the first important fact about this data. Each row in responses.csv is a single click, not a single participant. Forty people produced those twelve thousand rows.

Note that I happen to be telling you these facts. How might you know what each row represents?

The three files describe three different things:

  • participants — one row per person, with their identifiers and their progress through the study (whether they consented, how many tries the comprehension check took, whether they finished).
  • demographics — one row per person, with the age, gender, and education they reported.
  • responses — one row per click, recording which phase it happened in, which circle was clicked, and whether that click earned a point.

How the files connect

The files are linked by identifiers. Each participant has a unique id. In the other two files, the participantId column points back to that id. This is how you attach a person's demographics or their clicks to the person themselves.

Ask Claude:

Show one example participant end to end: pick a participant who completed the task, and
print their demographics and a summary of their responses (total clicks, clicks per
phase, and how many earned a point).

What comes back:

participant c0xiwarmi7  (consented, completed, comprehension passed on attempt 1)
  demographics:  age 49,  gender "Prefer not to say",  education "Some college"
  responses:     294 clicks total   (phase 1: 126,  phase 2: 140,  phase 3: 28)
  earned a point: 191 of 294 clicks

Reading the output: this single person consented, passed the comprehension check on the first try, and finished. They reported their age, gender, and education. During the task they clicked 294 times, most heavily in the first two phases and much less in the third, and 191 of those clicks earned a point. That drop in phase 3, from 126 and 140 clicks down to 28 makes sense with the experimental setup. It is the participant responding less once no clicks earn points, which is what we would expect and what a later lesson examines closely.

The vocabulary of a response

Three columns in responses.csv encode what the study measured, so it is worth learning their values now.

Ask Claude:

For responses.csv, show the counts of each value in the phase, button, and reinforced
columns.

What comes back:

phase:       {1: 5450, 2: 5471, 3: 878}
button:      {'R2': 5282, 'R1': 5231, 'distractor': 1286}
reinforced:  {'t': 8946, 'f': 2853}

Reading the output: phase is which of the three phases the click happened in, and there are far fewer clicks in phase 3 because it is shorter and because responding falls off when nothing earns points. button is which circle was clicked, using the labels R1, R2, and distractor. reinforced marks whether the click earned a point, stored as the text "t" for true and "f" for false. Notice that these counts come from the raw file, before any cleaning. They include every row as exported, which is the right starting point. The next lesson is about finding what in here should not be trusted yet.

Key points

  • Know the shape of your data, what one row means, and how the files connect before you analyze anything. You can't assume Claude will just know or will correctly figure it out.
  • In this dataset a row of responses.csv is one click, not one person. Forty people produced roughly twelve thousand rows.
  • The three files link through identifiers: a participant's id appears as participantId in the demographics and response tables.
  • The data you are working with is simulated, built to match the task you deployed, with a small set of real pilot participants kept separately.

Exercise

Load the three files yourself and, without looking at the example above, pick a different participant who completed the task. Print their demographics and their clicks per phase, and describe in one or two plain sentences what this person did during the study.

Checklist

Use this whenever you first open a new dataset. Read it yourself, and paste it to Claude to have it orient you before any analysis. A ready prompt is at the bottom.

  • The shape of every file is known (how many rows and columns each has).
  • What a single row represents in each file is stated in plain words.
  • The unit of analysis is clear (here, a response row is one click, not one participant).
  • How the files connect is identified (which column links to which).
  • The task or process that generated the data is understood well enough to interpret the columns.
  • It is clear which data is real and which is simulated, and why.

To use this with Claude, paste the checklist and add:

Orient me to the CSV files in data/synthetic/ before we analyze anything. Work through
each item: report the shape of each file, state what one row means, identify how the files
link together, and list any column whose meaning is unclear so I can explain it. Do not
run any analysis yet.