{smcl}
{* *! version 1.0.0  11May2026}{...}
{viewerjumpto "Syntax" "gtcsem_plot##syntax"}{...}
{viewerjumpto "Description" "gtcsem_plot##description"}{...}
{viewerjumpto "Options" "gtcsem_plot##options"}{...}
{viewerjumpto "Remarks" "gtcsem_plot##remarks"}{...}
{viewerjumpto "Examples" "gtcsem_plot##examples"}{...}
{viewerjumpto "References" "gtcsem_plot##references"}{...}
{viewerjumpto "Also see" "gtcsem_plot##alsosee"}{...}
{title:Title}

{phang}
{bf:gtcsem_plot} {hline 2} Plot conditional standard errors of
measurement after {help gtcsem}


{marker syntax}{...}
{title:Syntax}

{p 8 16 2}
{cmd:gtcsem_plot}
[{cmd:,} {it:options}]

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

{synoptset 22 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Plot content}
{synopt:{opth pl:ot(string)}}{cmd:csem}, {cmd:ci}, or {cmd:both};
default is {cmd:csem}{p_end}
{synopt:{opth abs:rel(string)}}{cmd:relative}, {cmd:absolute}, or
{cmd:both}; default is {cmd:relative}{p_end}
{synopt:{opt sm:ooth}}overlay the quadratic-smoothed CSEM curve{p_end}
{synopt:{opt comp:are}}overlay the three relative-error estimators
on a single panel (requires {cmd:gtcsem ..., method(all)}){p_end}

{syntab:Estimator selection}
{synopt:{opth meth:od(string)}}{cmd:full}, {cmd:large_a}, or
{cmd:uncorrelated}; default is {cmd:full}{p_end}
{synopt:{opth pre:fix(name)}}prefix of the {cmd:gtcsem}-generated
variables; default is read from {cmd:r(prefix)} or from the
dataset characteristic stored by {cmd:gtcsem}{p_end}

{syntab:Confidence bands}
{synopt:{opth ci(#)}}confidence level for the bands; default is
{cmd:ci(95)}{p_end}
{synopt:{opth cib:ands(string)}}{cmd:person} or {cmd:model};
default is {cmd:person}{p_end}
{synopt:{opth ase:method(string)}}{cmd:analytical} or
{cmd:bootstrap}; default is {cmd:analytical}{p_end}

{syntab:Graph cosmetics}
{synopt:{opt title(string)}}override the default plot title{p_end}
{synopt:{opt sub:title(string)}}override the default subtitle{p_end}
{synopt:{opt xt:itle(string)}}override the default x-axis title{p_end}
{synopt:{opt yt:itle(string)}}override the default y-axis title{p_end}
{synopt:{opt n:ame(string)}}name for the graph window{p_end}
{synopt:{opt saving(string)}}save the graph to disk{p_end}
{synopt:{it:twoway_options}}any other valid {help twoway} option is
passed through to the underlying {cmd:twoway} call{p_end}
{synoptline}


{marker description}{...}
{title:Description}

{pstd}
{cmd: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.

{pstd}
The command does not refit any model.  All quantities are read from
the variables generated by the previous {cmd:gtcsem} run, except
that under {cmd: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.


{marker options}{...}
{title:Options}

{dlgtab:Plot content}

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

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

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

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

{dlgtab:Estimator selection}

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

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

{dlgtab:Confidence bands}

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

{phang}
{opth cibands(string)} controls the source of the confidence bands.
{cmd: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.  {cmd:model} refits the quadratic
smoother on the per-person error variances, uses {cmd: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 {cmd:cibands(model)} the
{opt asemethod()} option is ignored.

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

{dlgtab:Graph cosmetics}

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

{phang}
{opt name(string)} and {opt saving(string)} are passed to {cmd:twoway}
unchanged.  Any other valid {help twoway} option (for example,
{cmd:scheme(...)}, {cmd:graphregion(...)}, {cmd:legend(...)}) is
also passed through.


{marker remarks}{...}
{title:Remarks}

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

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

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

{pstd}
which gives a symmetric Wald interval csem +/- z * SE[csem] truncated
at zero from below.  Under {cmd:cibands(person)}, Var[ev] is the
per-person variance written to the dataset by {cmd:gtcsem} (analytical
or bootstrap, as selected by {opt asemethod()}); the resulting
intervals reflect sampling uncertainty about each person's error
variance and need not be smooth across persons.  Under
{cmd: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.

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

{pstd}
{ul:Interaction with} {opt excludeextremes}{ul:.}  When {cmd:gtcsem}
was called with {opt excludeextremes}, the smoothed variables are
missing for floor and ceiling cases.  {cmd: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.

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


{marker examples}{...}
{title:Examples}

{pstd}Default scatter of relative CSEM against observed score:{p_end}
{phang2}{cmd:. gtcsem item1-item10}{p_end}
{phang2}{cmd:. gtcsem_plot}{p_end}

{pstd}Add the quadratic-smoothed curve:{p_end}
{phang2}{cmd:. gtcsem item1-item10, smooth}{p_end}
{phang2}{cmd:. gtcsem_plot, smooth}{p_end}

{pstd}Plot absolute and relative CSEMs side by side:{p_end}
{phang2}{cmd:. gtcsem_plot, absrel(both) smooth}{p_end}

{pstd}Person-level confidence bands using bootstrap variances:{p_end}
{phang2}{cmd:. gtcsem item1-item10, semethod(both) smooth}{p_end}
{phang2}{cmd:. gtcsem_plot, plot(ci) asemethod(bootstrap) smooth}{p_end}

{pstd}Smooth model-based confidence bands around the fitted curve:{p_end}
{phang2}{cmd:. gtcsem_plot, plot(both) cibands(model) smooth}{p_end}

{pstd}Pass an explicit prefix and a {help twoway} cosmetic option,
saving the graph to disk:{p_end}
{phang2}{cmd:. gtcsem_plot, prefix(myrun) smooth scheme(s2color) saving(csem_curve, replace)}{p_end}


{marker references}{...}
{title:References}

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

{phang}
Brennan, R. L. (2001). {it:Generalizability Theory}.
Springer-Verlag.


{marker author}{...}
{title:Author}

{pstd}Rene Gempp{break}
Facultad de Administracion y Economia, Universidad Diego Portales, Santiago, Chile{break}
Email: {browse "mailto:rene.gempp@udp.cl":rene.gempp@udp.cl}
{p_end}


{marker support}{...}
{title:Support and updates}

{pstd}
Bug reports, feature requests, and the development version are
available at {browse "https://github.com/rgempp/gtcsem"}.
{p_end}


{marker alsosee}{...}
{title:Also see}

{p 4 13 2}
Help: {help gtcsem}, {help twoway}