describe_dataset
Inspect a response file to confirm its layout, scoring, and column names, and review missing-data breakdown and subgroup sizes before running analyses. Use it first on any unfamiliar dataset.
Instructions
Load a response file and describe its shape, blanks and subgroups.
Call this FIRST on any unfamiliar file. It reports counts, the missing-data breakdown (omitted versus not-reached), and subgroup sizes, and it reproduces none of the responses themselves -- so it is safe to summarise in a conversation. Use it to confirm the layout, scoring and column names are right before running an analysis, and to check subgroup sizes before asking for DIF.
Relay the diagnostics warnings verbatim; they describe how blanks were
interpreted, which changes every downstream statistic.
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 |