*! version 1.0 2022.02.09
help uirt_esf

Title

uirt_esf -- Postestimation command of uirt to plot expected score functions for items and expected sum-score function for a set of items

Syntax

uirt_esf [varlist] [,options]

varlist must include only variables that were declared in the main list of items of current uirt run.
If varlist is skipped or asterisk * is used and no options are added,
uirt_esf will create IESF plots for all items declared in main list of items of current uirt run.

Options

tesf draws expected sum-score function (test characteristic curve) instead of IESF

all creates both IESF and TESF graphs

bins(#) number of ability intervals for observed mean scores; default: bins(100)

noobs suppress plotting observed mean scores

color(str) color name to override default color of ESF lines and markers

tw(twoway_options) twoway graph options to override default graph layout

format(str) file format for ESF graphs (png|gph|eps); default: format(png)

prefix(str) set the prefix of file names

suffix(str) set the suffix of file names

cleargraphs suppress storing of graphs in Stata memory

Description

uirt_esf is a postestimation command of uirt.
It allows to plot the expected score functions of individual items (IESF)
or the expected sum-score function of a test consisting of items provided in varlist (TESF).
On an item level it is similar to uirt_icc.
The difference is that uirt_icc draws probabilities of each response-category against theta,
whereas uirt_esf plots the expected item score against theta.
For binary items ICC and IESF are the same (only range of y-axis may be different, if item is not coded 0-1).
IESF becomes useful to analyze psychometric properties of polytomous items. Especially, when there are many response categories
(single curve characterizes performance of the item) or when numerical values of response categories are not equally spaced.
The test-level expected sum-score (TESF) is obtained with the tesf option. TESF is also called test characteristic curve (TCC).

Default behavior of uirt_esf is to superimpose means of observed scores against the estimated expected response curves.
This aids graphical assessment of model fit.
The observed mean scores are computed after quantile-based division of the distribution of latent variable, analogously as in uirt_icc.
Plotting observed mean scores is controlled by bins(), it can be also turned off by noobs.
Default look of graphs can be overridden by options: color() and tw().

Note that if ESF graphs for requested items are already saved in the working directory under default names, they will be overwritten after the command is repeated.
If you do not want to overwrite previous files, change the working directory, rename the existing files, or use prefix(str) or suffix(str) options.

Options

tesf creates a plot with the expected sum-score function of a test consisting of items provided in the varlist.
Such a plot is described with an acronym TESF in this help file, but it is also known as TCC (Test Characteristic Curve).

uirt_esf adds observed mean scores to all plots by default.
Note, that in case of TESF it is achieved by summation of the observed mean scores of individual items.
Even if the number of observations differ between items in your data (incomplete designs, missing data),
each item will be included with equal weight in the sum-score.

all results in plotting both the item-level IESF graphs, and the test-level TESF graph.

bins(#) sets the number of intervals the distribution of ability is split into
when calculating observed mean scores. Default value is bins(100).

noobs suppresses plotting observed proportions.

color(str) is used to override the default color (green) that is used for both the RF lines and the observed score markers.

tw(twoway_options) it is used to add user-defined twoway graph options to override the default graph layout,
like: xtitle() or scheme() etc.

format(str) specifies the file format in which the RF graphs are saved (png|gph|eps).
Default value is format(png).

prefix(str) is used to define a string that is added at the beginning of the names of saved files.
Default value for the item response functions is is prefix(esf). The test response function has no default prefix.

suffix(str) adds a user-defined string at the end of the names of saved files.
Default behavior is not to add any suffix.

cleargraphs is used to suppress the default behavior of storing all ICC graphs in Stata memory.
After specifying this, all graphs are still saved in the current working directory, but only the last graph is active in Stata.

Examples

Setup

. webuse masc1

. gen s_q8q9 = q8 + q9

Fit an IRT model to binary items q1-q7 and the artificial 3-categorical item s_q8q9 with uirt; create ICC plot for s_q8q9 with uirt_icc

. uirt q1-q7 s_q8q9

. uirt_icc s_q8q9, tw(title(Item s_q8q9: ICC plot))

Create IESF plot for s_q8q9, and combine the two graphs to compare information from ICC and IESF

. uirt_esf s_q8q9, tw(title("Item s_q8q9: IESF plot"))

. gr combine ICC_s_q8q9 IESF_s_q8q9

Create TESF plot for all items used in the current uirt run

. uirt_esf *, tesf

Stored results

uirt_esf does not store anything in r():

Author

Bartosz Kondratek
everythingthatcounts@gmail.com