# A fictional data-cleaning handover

This small package illustrates a research-data handover. Every record and
number is invented. It includes no real respondent information, client work,
institutional results, or evidence of programme impact.

## Hypothetical brief

Prepare an invented adult-workshop survey export for review. Standardise
documented categorical spellings, remove one exact repeated record, and flag
missing or out-of-range values. Preserve the source data and provide the
processing rules and outputs together.

## Files

| File | Purpose |
| --- | --- |
| `raw-survey.csv` | Untouched fictional input: 13 records and five fields. |
| `cleaned-survey.csv` | 12 retained records, original values, prepared fields, and review flags. |
| `codebook.md` | Variable meanings, explicit recoding, illustrative thresholds, and flag definitions. |
| `cleaning-log.csv` | Record-level changes, duplicate removal, and unresolved issues. |
| `clean-survey.py` | Reproducible script using Python 3's standard library only. |
| `summary.json` | Counts and limited descriptive arithmetic generated by the script. |

## Reproduce the outputs

Save the files in the same folder. Run from a terminal with Python 3:

```text
python3 clean-survey.py
```

The script creates a new `reproduced/` folder beside itself containing the
cleaned CSV, cleaning log, and JSON summary. It reads the raw file without
changing it. The default output folder keeps the supplied handover files
available for comparison. Rerunning replaces the files inside `reproduced/`.
You can choose other local paths:

```text
python3 clean-survey.py --input raw-survey.csv --output-dir another-output
```

No package installation, network access, accounts, or data upload is needed.
The script is scoped to this five-field questionnaire, not a general-purpose
cleaner for arbitrary survey exports.

## Expected results

| Check | Generated result |
| --- | ---: |
| Raw records | 13 |
| Exact duplicate records removed | 1 |
| Retained records | 12 |
| Records passing all listed demo checks | 6 |
| Retained records requiring review | 6 |
| Delivery-mode values normalised (retained records) | 10 |
| Attendance values normalised (retained records) | 8 |
| Age range flags | 2 |
| Study-hours range flags | 1 |
| Missing ID flags | 1 |
| Missing study-hours flags | 1 |
| Unrecognised delivery-mode flags | 1 |

The duplicate at source record 14 matches record 4 exactly. It is logged and
removed. Six retained records each have one review flag. Nothing is imputed:
an unresolved numeric or category value is blank in the prepared field, its
original value remains in `_raw`, and the row remains in the cleaned file.
The hypothetical next step is to verify flagged responses against the source;
this package does not invent a resolution.

The six passing records contain four attendance `yes` responses and two `no`
responses. Their study hours total 37, giving a mean of 6.17 hours rounded to
two decimals. The denominator and the exclusion of six unresolved records
are explicit. These values have no meaning outside the fictional example.