{smcl}
{* *! version 2.0 || 23.7.2026 || Gordey Yastrebov}{...}
{hi:help apcdescribe}{...}
{right:also see: {helpb apcest}, {helpb apcbound}, {helpb apcplot}}
{hline}


{title:Title}

{pstd}{hi:apcdescribe} {hline 2} A tool for plotting unadjusted descriptive age, period, and cohort patterns (part of the {cmd:apcbound} package).


{title:Syntax}

{p 8 15 2}{cmd:apcdescribe} {varname} {ifin} {weight},
{help apcdescribe##specifications:{it:APC_variable_specifications}}
[{help apcdescribe##options:{it:options}}]

{pstd}where {it:varname} is the numeric outcome variable to be plotted and {help apcdescribe##specifications:{it:APC_variable_specifications}} are one or more of {opt a(specification)}, {opt p(specification)}, and {opt c(specification)}. At least one APC variable must be specified.

{synoptset 42 tabbed}
{synopthdr:options}
{synoptline}

{syntab:{help apcdescribe##styling:Graph styling options}}
{synopt:{opt b:inpos(center|mean)}}position of grouped values; default is {cmd:center}{p_end}
{synopt:{opt li:neops}({help scatter:{it:scatter_options}})}common options for estimate layers{p_end}
{synopt:{opt a|p|cli:neops}({help scatter:{it:scatter_options}})}APC-specific options for estimate layers{p_end}
{synopt:{opt pl:otops}({it:{help twoway_options}})}common options for complete graphs{p_end}
{synopt:{opt a|p|cpl:otops}({it:{help twoway_options}})}APC-specific options for complete graphs{p_end}
{synopt:{opt comb:ined}}combine requested graphs{p_end}
{synopt:{opt combpl:otops}({help graph_combine:{it:combined_options}})}combined-graph options{p_end}

{syntab:{help apcdescribe##confidence:Confidence interval options}}
{synopt:{opt ci(#)}}plot pointwise confidence intervals at confidence level {it:#}{p_end}
{synopt:{opt recast:ci}({help graph_twoway:{it:plottype}})}CI plot type; default is {cmd:rarea}{p_end}
{synopt:{opt cipl:otops}({it:{help twoway_options}})}common options for CI layers{p_end}
{synopt:{opt a|p|ccipl:otops}({it:{help twoway_options}})}APC-specific options for CI layers{p_end}

{synoptline}
{p 4 6 2}{cmd:aweight}s, {cmd:fweight}s, {cmd:pweight}s, and {cmd:iweight}s are allowed for descriptive means. Local-polynomial curves allow {cmd:aweight}s and {cmd:fweight}s only. {cmd:ci()} is not supported with {cmd:pweight}s or {cmd:iweight}s.{p_end}


{title:Description}

{pstd}{cmd:apcdescribe} plots unadjusted descriptive patterns in an outcome across age, period, and/or cohort. Each APC dimension may be represented by means at its distinct values, means within temporary groups, or a kernel-weighted local polynomial curve estimated from the original ungrouped observations. The patterns are descriptive rather than model-based APC effects and are not adjusted for the other APC dimensions or for covariates.

{pstd}Pointwise confidence intervals are added only when {opt ci()} is specified. For distinct-value and grouped means, they are based on the mean and its standard error; for local-polynomial curves, they use the standard errors generated by {helpb lpoly}. Restrictions supplied with {cmd:if} and {cmd:in} are applied before calculation. The command preserves the dataset in memory.


{marker options}{title:Options}

{marker specifications}{dlgtab:APC specifications}

{phang}{opt a(specification)}, {opt p(specification)}, and {opt c(specification)} designate the age, period, and cohort variables and their descriptive specifications. Any combination of one, two, or all three dimensions is allowed. Each specification must identify one numeric variable; variable lists, factor-variable notation, time-series operators, and expressions are not allowed.

{pmore}A variable name alone, as in {cmd:a(age)}, requests outcome means at every distinct observed value. The form {cmd:varname:}{it:{help numlist}}, as in {cmd:c(cohort:1900(10)2000)}, requests grouped means; the {it:{help numlist}} must contain at least two strictly increasing cut points, and values outside the specified intervals are excluded from that dimension's graph.

{pmore}The form {cmd:varname:}{it:{help lpoly}}, as in {cmd:a(age:lpoly)}, requests a kernel-weighted local polynomial curve using the original ungrouped observations. Local-polynomial options may follow an internal comma; 
see {help lpoly##options:{it:lpoly_options}}. One-letter option abbreviations are allowed.

{phang}{opt binpos(center|mean)} determines the horizontal position of grouped values and has no effect on distinct-value means or local-polynomial curves. Option {cmd:center}, the default, uses interval midpoints; option {cmd:mean} uses the observed mean of the APC variable within each interval, calculated from the same sample and weights as the corresponding outcome mean.


{marker styling}{dlgtab:Graph styling options}

{phang}{opt lineops}({help scatter:{it:scatter_options}}) specifies options for the central estimate layer in every requested graph. Distinct-value and grouped means are shown as markers connected by a line; local-polynomial estimates are connected by a line with markers hidden by default. Marker, marker-label, line, and connection options accepted by {help twoway scatter:{cmd:scatter}} may be specified.

{phang}{opt alineops}({help scatter:{it:scatter_options}}), {opt plineops}({help scatter:{it:scatter_options}}), and {opt clineops}({help scatter:{it:scatter_options}}) specify age-, period-, and cohort-specific estimate-layer options. They are applied after {opt lineops()} and therefore override conflicting common options.

{phang}{opt plotops}({it:{help twoway_options}}) specifies options for each complete {cmd:twoway} graph. {opt aplotops()}, {opt pplotops()}, and {opt cplotops()} specify dimension-specific complete-graph options and are applied after {opt plotops()}.

{phang}{opt combined} combines two or three requested graphs in one row with a common vertical scale. If only one dimension is requested, it has no effect. {opt combplotops}({help graph_combine:{it:combined_options}}) specifies options for the combined graph.


{marker confidence}{dlgtab:Confidence interval options}

{phang}{opt ci(#)} adds pointwise confidence intervals at confidence level {it:#}, where {it:#} must be greater than 0 and less than 100. No intervals are shown by default. For mean-based specifications, cells with fewer than two usable observations or without a calculable standard error have missing limits.

{phang}{opt recastci}({help graph_twoway:{it:plottype}}) selects the graph type used for all confidence intervals. The default is {help twoway_rarea:rarea}; {help twoway_rcap:rcap}, {help twoway_rspike:rspike}, and {help twoway_rline:rline} are also allowed. The option requires {opt ci()}.

{phang}{opt ciplotops}({it:{help twoway_options}}) specifies common options for confidence-interval layers. {opt aciplotops()}, {opt pciplotops()}, and {opt cciplotops()} specify dimension-specific CI-layer options and are applied after {opt ciplotops()}. These options require {opt ci()} and must be valid for the graph type selected by {opt recastci()}.


{title:Examples}

{pstd}Load sample data:

	. {stata webuse nlswork, clear}

{pstd}Plot means at the distinct observed values of age, period, and cohort:

	. {stata apcdescribe ln_wage, a(age) p(year) c(birth_yr)}

{pstd}Combine the three graphs using a common vertical scale:

	. {stata apcdescribe ln_wage, a(age) p(year) c(birth_yr) combined}

{pstd}Plot age, period, and cohort in grouped intervals:

	. {stata "apcdescribe ln_wage, a(age:10(5)50) p(year:68(5)93) c(birth_yr:40(5)60) combined"}

{pstd}Position grouped estimates at the observed within-bin means rather than interval midpoints:

	. {stata "apcdescribe ln_wage, a(age:10(5)50) p(year:68(5)93) c(birth_yr:40(5)60) binpos(mean) combined"}

{pstd}Plot an age local-polynomial curve using Stata's defaults:

	. {stata "apcdescribe ln_wage, a(age:lpoly)"}

{pstd}Plot a local-linear age curve with bandwidth 3 using abbreviated options:

	. {stata "apcdescribe ln_wage, a(age:lpoly, d(1) b(3))"}

{pstd}Use a local-polynomial age curve, period-specific means, and five-year cohort groups in one combined graph:

	. {stata "apcdescribe ln_wage, a(age:lpoly, d(1) b(3)) p(year) c(birth_yr:40(5)60) combined"}

{pstd}Add 95% confidence intervals; shaded areas are used by default:

	. {stata "apcdescribe ln_wage, a(age:lpoly, d(1) b(3)) p(year) c(birth_yr:40(5)60) ci(95) combined"}

{pstd}Apply common line styling and override it for the cohort graph:

	. {stata "apcdescribe ln_wage, a(age:lpoly, d(1) b(3)) p(year) c(birth_yr:40(5)60) lineops(lc(gs8) lw(medthick)) clineops(lc(black) lp(dash)) combined"}

{pstd}Customize the default CI areas and override them for the age graph:

	. {stata "apcdescribe ln_wage, a(age:lpoly, d(1)) p(year) ci(95) ciplotops(color(gs12)) aciplotops(color(gs10)) combined"}

{pstd}Recast confidence intervals as capped spikes:

	. {stata "apcdescribe ln_wage, a(age:10(5)50) p(year) ci(90) recastci(rcap) ciplotops(lc(gs8)) combined"}



{title:Author}

{p 4}{cmd:Gordey Yastrebov}{p_end}
{p 4}{it:University of Cologne}{p_end}
{p 4}{browse "mailto:gordey.yastrebov@gmail.com":gordey.yastrebov@gmail.com}{p_end}


{title:Citation}

{pstd}When referring to {cmd:apcbound}, {cmd:apcest}, {cmd:apcplot}, or {cmd:apcdescribe} in published work, please consider citing the software package and the article implementing the bounding approach:{p_end}

{phang}{cmd:Yastrebov, G.} (2026). "APCBOUND: Stata module for the Fosse-Winship bounding approach to age-period-cohort analysis (Version 2.0)" [Computer software]. Boston College Department of Economics, Statistical Software Components.
{browse "https://ideas.repec.org/c/boc/bocode/s459449.html":https://ideas.repec.org/c/boc/bocode/s459449.html}{p_end}

{phang}{cmd:Yastrebov, G., Trinidad, A., and Leopold, T.} (2025). A Bounding Approach to Age-Period-Cohort Analysis: A Demonstration Using Public Crime Concerns in Germany. {it:Journal of Quantitative Criminology}. 
{browse "https://doi.org/10.1007/s10940-025-09633-7":https://doi.org/10.1007/s10940-025-09633-7}{p_end}