# Fictional survey demonstration: codebook

All records, identifiers, responses, and summary figures are invented for this
demonstration. There are no real respondents, institutions, or client outcomes.
These rules illustrate a handover; they are not a universal survey protocol.

## Hypothetical questionnaire and validation rules

The invented questionnaire is for an adult workshop and has five fields.
The validation rules below are assumptions of this demonstration. In a real
project they would need agreement with the researcher and source verification.

| Raw field | Meaning | Type and demo rule |
| --- | --- | --- |
| `record_id` | Invented response identifier | Text. Required and unique after exact duplicate removal. Trim surrounding whitespace only. Do not create a missing ID. |
| `age_years` | Age in whole years | Integer, 18–100 inclusive. This is an adult-workshop eligibility check. |
| `delivery_mode` | Requested workshop format | `online` or `in_person` using the explicit mapping below. |
| `study_hours_week` | Self-reported study hours in a typical week | Number, 0–20 inclusive. The upper limit is an illustrative review threshold, not proof that a larger value is impossible. |
| `attended_session` | Whether the invented respondent attended one session | `yes` or `no` using the explicit mapping below. |

## Explicit recoding

For categorical lookup, strip surrounding whitespace and compare without
case sensitivity. The cleaned values are lowercase.

| Field | Accepted raw spellings | Cleaned value |
| --- | --- | --- |
| `delivery_mode` | `online`, `on-line`, `remote` | `online` |
| `delivery_mode` | `in person`, `in-person`, `in_person` | `in_person` |
| `attended_session` | `yes`, `y`, `1` | `yes` |
| `attended_session` | `no`, `n`, `0` | `no` |

The mapping of `remote` to `online` is assumed for this invented questionnaire.
`hybrid` has no mapping and requires review. Do not infer a replacement.

## Cleaned-file fields

| Field | Meaning |
| --- | --- |
| `source_row` | 1-based CSV record index in the original raw file, including the header as record 1. For this single-line-per-record file this is also the line number. |
| `record_id_raw`, `age_years_raw`, `delivery_mode_raw`, `study_hours_week_raw`, `attended_session_raw` | The exact original values for each retained record. Blank strings remain blank. |
| `record_id`, `age_years`, `delivery_mode`, `study_hours_week`, `attended_session` | The prepared fields. Unresolved invalid numeric or categorical values are blank; the original value remains in the corresponding `_raw` field. |
| `review_flags` | Semicolon-separated codes for unresolved issues. Blank means the record passed the listed demo checks. |
| `passes_checks` | `yes` when `review_flags` is blank; otherwise `no`. This describes only the checks in this codebook, not fitness for every analysis. |

CSV does not carry types: import `record_id` as text and the prepared age and
hours fields as numbers, preserving blank values as missing rather than zero.

## Review flags

| Code | Meaning |
| --- | --- |
| `missing_record_id` | Response identifier is absent. |
| `repeated_record_id` | Different retained records share a nonblank ID. The script flags every occurrence and keeps them for review. There are none in the supplied demonstration. |
| `age_years_out_of_range` | Whole-number age is outside 18–100. |
| `study_hours_week_out_of_range` | Study hours are outside 0–20. |
| `missing_study_hours_week` | Study-hours response is absent. |
| `unrecognised_delivery_mode` | Format is outside the explicit map. |
| `missing_age_years`, `missing_delivery_mode`, `missing_attended_session` | Required response is absent. Supported by the script; absent in the supplied data. |
| `invalid_age_years`, `invalid_study_hours_week` | Value fails the documented numeric type, including nonfinite values. Supported by the script; absent in the supplied data. |
| `unrecognised_attended_session` | Attendance response is outside the explicit map. Supported by the script; absent in the supplied data. |

## Deduplication and summaries

Remove only exact duplicates across all five original raw values, keeping the
first occurrence and logging which source record it matches. This does not
authorize dropping different records with the same ID or treating similarly
worded responses as duplicates.

The downloadable summary uses only the six retained records with
`passes_checks=yes`. Their study hours total 37; 37 ÷ 6 = 6.17 hours rounded to
two decimal places. Attendance is four `yes` and two `no`; delivery mode is four
`online` and two `in_person`. Six other retained records remain pending review.
These are arithmetic examples for fictional responses, with no population,
programme-effectiveness, or client-performance interpretation.