*! version 1.0.0 11May2026

Title

gtcsem_plot -- Plot conditional standard errors of
measurement after gtcsem

Syntax

gtcsem_plot
[, options]

gtcsem_plot is a post-estimation companion to gtcsem
and must be issued after a gtcsem call against the same
dataset. It reads the variable prefix and the estimation options
from the most recent gtcsem return values, and falls back to
the dataset characteristics that gtcsem stores when those
return values have been wiped by intervening r-class commands.

Plot content
plot(string) csem, ci, or both;
default is csem

absrel(string) relative, absolute, or
both; default is relative

smooth overlay the quadratic-smoothed CSEM curve

compare overlay the three relative-error estimators
on a single panel (requires gtcsem ..., method(all))

Estimator selection
method(string) full, large_a, or
uncorrelated; default is full

prefix(name) prefix of the gtcsem-generated
variables; default is read from r(prefix) or from the
dataset characteristic stored by gtcsem

Confidence bands
ci(#) confidence level for the bands; default is
ci(95)

cibands(string) person or model;
default is person

asemethod(string) analytical or
bootstrap; default is analytical

Graph cosmetics
title(string) override the default plot title

subtitle(string) override the default subtitle

xtitle(string) override the default x-axis title

ytitle(string) override the default y-axis title

name(string) name for the graph window

saving(string) save the graph to disk

twoway_options any other valid twoway option is
passed through to the underlying twoway call

Description

gtcsem_plot produces Brennan-style plots of the per-person
conditional standard error of measurement (CSEM) against the
observed score. In its default form, the plot is a scatter of
each person's CSEM at the person's observed score; optionally, a
quadratic-smoothed curve, confidence bands, and overlays of the
three relative-error estimators may be added.

The command does not refit any model. All quantities are read from
the variables generated by the previous gtcsem run, except
that under cibands(model) the quadratic smoother is refit on
the per-person error variances to obtain a smooth confidence band
around the fitted curve via the delta method.

Options

Plot content

plot(string) controls the visual layers shown. csem
(the default) draws only the per-person CSEM scatter; ci draws
only the confidence bands (and the smoothed curve when smooth
is also requested); both draws the bands together with the
scatter.

absrel(string) selects which CSEM is plotted. relative
(the default) plots the relative CSEM (sigma(delta_p));
absolute plots the absolute CSEM (sigma(Delta_p)); both
overlays the two on a single panel and adds a legend that
distinguishes them.

smooth overlays the quadratic-smoothed CSEM curve produced by
gtcsem ..., smooth. If the smoothed variables do not exist in
the dataset (because gtcsem was run without smooth), the
overlay is silently dropped.

compare overlays the full, large_a, and
uncorrelated relative CSEMs on a single panel, with a legend
identifying each estimator. Requires that the previous gtcsem
call used method(all). Under compare the absrel()
and method() options are ignored, and only the relative CSEM
family is shown.

Estimator selection

method(string) selects which of the three relative-error
estimators is plotted, in cases where gtcsem was called with
method(all). Has no effect when gtcsem was called with a
single-method specification (the only available estimator is
plotted).

prefix(name) sets the variable prefix to be used when reading
the data to plot. By default it is recovered from r(prefix);
if r() has been wiped, it falls back to the dataset
characteristic char _dta[gtcsem_prefix] stored by
gtcsem. Supplying it explicitly is recommended in robust
do-files (see Remarks).

Confidence bands

ci(#) sets the confidence level (in percent, strictly between
0 and 100) for the bands drawn by plot(ci) or plot(both).
Default is 95.

cibands(string) controls the source of the confidence bands.
person (the default) uses each person's variance estimate of
the per-person error variance and draws an interval at every
observed score, producing a possibly jagged ribbon that connects
individual person intervals. model refits the quadratic
smoother on the per-person error variances, uses predict, stdp
to obtain the standard error of the mean fit, and propagates that
SE to the CSEM scale via the delta method, producing a smooth band
around the fitted curve. Under cibands(model) the
asemethod() option is ignored.

asemethod(string) selects which of the per-person variance
columns is used by cibands(person). analytical (the
default) uses the closed-form variances; bootstrap uses the
bootstrap variances. bootstrap requires that gtcsem was
called with semethod(bootstrap) or semethod(both).

Graph cosmetics

title(string), subtitle(string), xtitle(string),
ytitle(string) override the corresponding default texts. If
omitted, sensible defaults are constructed from the absrel(),
plot(), cibands(), and ci() settings (for
example, the default subtitle for plot(ci) reports the
nominal coverage and the variance source).

name(string) and saving(string) are passed to twoway
unchanged. Any other valid twoway option (for example,
scheme(...), graphregion(...), legend(...)) is
also passed through.

Remarks

Recovering gtcsem state. By default gtcsem_plot
relies on r(prefix) and r(method). Stata's r-class
return values are however overwritten by any intervening r-class
command, including innocuous ones such as summarize or
tabulate. To make plot calls robust against this, gtcsem
also stores the prefix and the relevant options as dataset
characteristics (char _dta[gtcsem_prefix],
char _dta[gtcsem_method],
char _dta[gtcsem_excludeextremes], etc.), which gtcsem_plot
falls back to when r() has been cleared. In production
do-files, the safest pattern is to pass prefix() explicitly.

Confidence-band construction. Both modes of cibands()
move from the error-variance scale to the CSEM scale by the delta
method:

SE[csem] = sqrt(Var[ev]) / (2 * csem)

which gives a symmetric Wald interval csem +/- z * SE[csem] truncated
at zero from below. Under cibands(person), Var[ev] is the
per-person variance written to the dataset by gtcsem (analytical
or bootstrap, as selected by asemethod()); the resulting
intervals reflect sampling uncertainty about each person's error
variance and need not be smooth across persons. Under
cibands(model), Var[ev] is replaced by the squared SE of the
fitted value from a refit quadratic regression of the per-person
error variance on the observed score, yielding smooth bands centred
on the smoothed curve. Persons whose CSEM is zero or missing receive
missing band endpoints.

Bootstrap bands. Selecting asemethod(bootstrap) requires
that the per-person bootstrap variances are present in the dataset,
which in turn requires that gtcsem was called with
semethod(bootstrap) or semethod(both). Otherwise the
command exits with an informative error.

Interaction with excludeextremes. When gtcsem
was called with excludeextremes, the smoothed variables are
missing for floor and ceiling cases. gtcsem_plot restricts the
raw scatter and the confidence bands to the same non-extreme sample
(detected as the rows where the smoothed variable is non-missing),
so that the displayed cloud and the fitted line cover the same
persons.

Repeated calls. Unlike gtcsem, gtcsem_plot is not
declared rclass, so it does not wipe the caller's r() on
exit. This means it can be invoked multiple times after a single
gtcsem call to produce alternative views (for example, raw
scatter first, then bands, then a method comparison) without
re-running the estimator.

Examples

Default scatter of relative CSEM against observed score:

. gtcsem item1-item10

. gtcsem_plot

Add the quadratic-smoothed curve:

. gtcsem item1-item10, smooth

. gtcsem_plot, smooth

Plot absolute and relative CSEMs side by side:

. gtcsem_plot, absrel(both) smooth

Person-level confidence bands using bootstrap variances:

. gtcsem item1-item10, semethod(both) smooth

. gtcsem_plot, plot(ci) asemethod(bootstrap) smooth

Smooth model-based confidence bands around the fitted curve:

. gtcsem_plot, plot(both) cibands(model) smooth

Pass an explicit prefix and a twoway cosmetic option,
saving the graph to disk:

. gtcsem_plot, prefix(myrun) smooth scheme(s2color) saving(csem_curve, replace)

References

Brennan, R. L. (1998). Raw-score conditional standard errors of
measurement in Generalizability Theory.
Applied Psychological Measurement, 22(4), 307-331.
https://doi.org/10.1177/014662169802200402

Brennan, R. L. (2001). Generalizability Theory.
Springer-Verlag.

Author

Rene Gempp

Facultad de Administracion y Economia, Universidad Diego Portales, Santiago, Chile

Email: rene.gempp@udp.cl

Support and updates

Bug reports, feature requests, and the development version are
available at https://github.com/rgempp/gtcsem.

Also see

Help: gtcsem, twoway