compute_local_dependence
Screen every item pair for local dependence using Yen's Q3 and flag entangled pairs that measure the same thing twice, isolating residual covariance beyond the trait.
Instructions
Screen every item pair for local dependence (Yen's Q3) and flag entangled pairs.
Answers a question compute_classical_stats structurally cannot: whether two
items are measuring the same thing twice. Q3 is the correlation between two
items' residuals once the common factor is removed, so it isolates covariance
that the trait does not explain -- one item cueing the answer to another,
a shared stimulus, or near-duplicate content. Every item on a form can pass
every per-item check and the form can post a healthy alpha while a fifth of
its items are entangled; that is the case for running this at all.
Returns the flagged pairs, each with its Q3, its centred Q3*, how many SDs from
the form mean it sits, and a flag object, plus the whole Q3 distribution the
pairs were judged against -- a flag list without its reference distribution
cannot be read. summary.hub_items names items that appear in three or more
flagged pairs, reported separately because a hub is one item to fix rather than
several pairs to triage.
REFUSES below 5 items or 100 examinees, and refuses with no_estimable_pairs
when every pair involves a zero-variance item -- a distinct refusal because
more examinees would not fix it.
Two things this deliberately is not. It is not an enemy-item check: overlapping
content is a content-similarity question, and Q3 supplies only the statistical
half, so a flagged pair is a pair to READ, not a pair to cut. And it is not
inference -- there are no p-values here, for the reason given in method. Do
not present a flagged pair as a significant finding.
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. | |
| threshold | No | How far above the form's mean Q3 a pair must sit to be flagged. The 0.20 default is settled screening practice rather than a derived critical value, so it is adjustable: lowering it toward 0.10 surfaces pairs a content reviewer will mostly dismiss, and raising it toward 0.30 will miss the moderate cueing that item review is best at catching. It is a correlation, so 20 means 20 -- pass 0.2, not 20. | |
| 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 |
| max_pairs_returned | No | Cap on how many flagged pairs come back, largest |Q3*| first. Guards the transcript rather than the analysis: the count of pairs flagged is always reported in full, and `summary.truncated` says when the list is partial. Raising it on a form that flags hundreds of pairs will fill the reply with a form-level problem restated pair by pair. | |
| threshold_reference | No | What `threshold` is measured against. 'centred' (default) compares each pair to this form's own mean Q3, which is what makes one cutoff comparable across forms of different lengths -- Q3 is biased downward by about -1/(n_items - 1) purely by construction. 'absolute' compares the raw Q3 and exists only for reconciling with other software: on a short form it is lopsided, flagging negative pairs for no reason and being nearly impossible to trip positively, so a 12-item form with no dependence at all can return five invented pairs. | centred |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |