*! version 2.0 || 23.7.2026 || Gordey Yastrebov
help apcdescribealso see: apcest, apcbound, apcplot

Title

apcdescribe -- A tool for plotting unadjusted descriptive age, period, and cohort patterns (part of the apcbound package).

Syntax

apcdescribe varname [if] [in] [weight],
APC_variable_specifications
[options]

where varname is the numeric outcome variable to be plotted and APC_variable_specifications are one or more of a(specification), p(specification), and c(specification). At least one APC variable must be specified.

options

Graph styling options
binpos(center|mean) position of grouped values; default is center

lineops(scatter_options) common options for estimate layers

a|p|clineops(scatter_options) APC-specific options for estimate layers

plotops(twoway_options) common options for complete graphs

a|p|cplotops(twoway_options) APC-specific options for complete graphs

combined combine requested graphs

combplotops(combined_options) combined-graph options

Confidence interval options
ci(#) plot pointwise confidence intervals at confidence level #

recastci(plottype) CI plot type; default is rarea

ciplotops(twoway_options) common options for CI layers

a|p|cciplotops(twoway_options) APC-specific options for CI layers

aweights, fweights, pweights, and iweights are allowed for descriptive means. Local-polynomial curves allow aweights and fweights only. ci() is not supported with pweights or iweights.

Description

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.

Pointwise confidence intervals are added only when 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 lpoly. Restrictions supplied with if and in are applied before calculation. The command preserves the dataset in memory.

Options

APC specifications

a(specification), p(specification), and 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.

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

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

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

Graph styling options

lineops(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 scatter may be specified.

alineops(scatter_options), plineops(scatter_options), and clineops(scatter_options) specify age-, period-, and cohort-specific estimate-layer options. They are applied after lineops() and therefore override conflicting common options.

plotops(twoway_options) specifies options for each complete twoway graph. aplotops(), pplotops(), and cplotops() specify dimension-specific complete-graph options and are applied after plotops().

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. combplotops(combined_options) specifies options for the combined graph.

Confidence interval options

ci(#) adds pointwise confidence intervals at confidence level #, where # 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.

recastci(plottype) selects the graph type used for all confidence intervals. The default is rarea; rcap, rspike, and rline are also allowed. The option requires ci().

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

Examples

Load sample data:

. webuse nlswork, clear

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

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

Combine the three graphs using a common vertical scale:

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

Plot age, period, and cohort in grouped intervals:

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

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

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

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

. apcdescribe ln_wage, a(age:lpoly)

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

. apcdescribe ln_wage, a(age:lpoly, d(1) b(3))

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

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

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

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

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

. 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

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

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

Recast confidence intervals as capped spikes:

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

Author

Gordey Yastrebov

University of Cologne

gordey.yastrebov@gmail.com

Citation

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

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.
https://ideas.repec.org/c/boc/bocode/s459449.html

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