compute_classical_stats
Computes classical item analysis: item difficulty, discrimination, and form reliability, with diagnostic flags to identify problematic items for review.
Instructions
Classical item analysis: difficulty, discrimination and form reliability.
Returns per item: p-value with a Wilson 95% interval, corrected point-biserial (item versus rest score -- the discrimination index to use), uncorrected point-biserial, biserial, the 27% upper-lower D index, and review flags. Returns per form: mean and SD of total score, Cronbach's alpha (identical to KR-20 here by construction), the standard error of measurement, and alpha-if-item-deleted.
REFUSES below 20 examinees and warns below 100.
Read the flags as review triggers, not verdicts. In particular, a negative corrected point-biserial on an item of ordinary difficulty usually means the item is mis-keyed rather than that it is a bad item -- the diagnostics say so explicitly when it occurs, and that warning must be relayed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| layout | No | 'wide' -- one row per examinee, one column per item. 'long' -- one row per examinee-item response, which requires `id_column` and expects `item_id` and `response` columns. | wide |
| scored | No | True if the cells already hold 0/1 item scores. False if they hold the option each examinee selected (e.g. 'A', 'C'), which requires `answer_key`. This is never inferred: a raw-option file read as scored produces a complete, plausible-looking analysis of nothing. Confirm it with `describe_dataset` before trusting any statistic. | |
| id_column | No | Name of the examinee identifier column. Naming it excludes it from the item columns; leaving it unnamed makes it an extra 'item'. Identifiers are used only for exclusion and are never returned. | |
| answer_key | No | Correct option for each item, in the same order as the item columns. Required when `scored=False`; ignored otherwise. Its length must equal the item count -- a key that is off by one mis-scores every item after the offset, and the result looks like a form-wide item-quality problem. One entry per item, holding the option itself -- not its position, and not the whole key as a single string. | |
| linear_form | No | True if every examinee saw the items in column order, which is what makes a trailing run of blanks readable as not-reached. Set False for adaptive or randomised-order delivery: position is then unknown, so all blanks are treated as omits and a warning says so. | |
| group_column | No | Name of a subgroup column (demographic or otherwise). Naming it excludes it from the item columns and reports subgroup sizes. Optional here; required by `flag_dif`. | |
| response_file | Yes | Path to the response file on disk, read locally. Candidate responses are passed as a path and never inline, so that a multi-thousand-examinee file does not enter the conversation transcript. | |
| missing_policy | No | How blank responses are scored. 'omit_incorrect_notreached_missing' (default) scores a blank mid-form as incorrect -- the examinee had the opportunity -- and excludes a trailing run of blanks as not-reached, because scoring those wrong confounds item difficulty with speededness. 'all_incorrect' scores every blank wrong, which makes end-of-form items look harder and less discriminating in proportion to how speeded the form is; use it only if the scoring rules genuinely penalise unreached items. 'all_missing' excludes every blank, which conditions p-values on having attempted the item and turns items examinees skip when unsure into easy-looking ones. The two non-default policies each raise a warning. | omit_incorrect_notreached_missing |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |