*! survcollapse.sthlp

*! v1.0 17Jan2026 Leonelo Bautista

Help for survcollapseCopy

Title

survcollapse -- Collapses surveillance data over a chosen time unit, and creates flagged observations for missing time units.

Syntax

survcollapse [if] [in],
datevar(varname) casevar(varname) timevar(varname) saving(filename) [keepvars(varlist) replace]

Description

survcollapse collapses surveillance data in which each observation may represent a single case
or multiple cases occurring on the same date (time unit), producing totals over a user-selected
coarser time unit (for example, aggregating daily data to weekly or monthly data). It ensures
that the resulting time series is complete: observations for time units (e.g., days) that did not
exist in the original dataset are automatically created and assigned 0 cases. Only gaps between
the minimum and maximum observed value of timevar() are completed. The flag variable created
indicates whether a time unit was observed in the original data (created = 0) or was generated by
survcollapse and assigned 0 cases in the collapsed data (created = 1).

survcollapse is not a replacement for collapse. It aggregates counts using a sum over
casevar() within groups defined by keepvars() and timevar(). In addition, survcollapse
explicitly creates observations for missing time units and assigns them a value of 0 cases, producing a
complete time series, while collapse only retains combinations of grouping variables that already
exist in the data.

Grouping (e.g., national, province, region) is controlled by the user through optional keepvars()
and optional if/in qualifiers. survcollapse collapses by the selected timevar()
only; keepvars() is retained as a constant identifier in the output.

Options

Required

datevar(varname) specifies the least coarse time variable in the dataset (e.g., a Stata daily date)
over which cases are reported. This variable is used as the time reference for generating the selected
timevar() and for completing missing time units.

casevar(varname) specifies the numeric case-count variable to be summed by survcollapse.

timevar(varname) specifies the type of time variable that survcollapse will generate
from datevar() and use as the collapsing time unit. Allowed formats are:

__day daily time unit. This is a numeric Stata daily date variable, with values corresponding
to the number of days since 01jan1960. If the variable year does not exist, it could be created
with gen int year = year(__day).

stata_week Stata week series (Sunday-based weeks). When this option is used, survcollapse
outputs year and week (week-of-year), Stata's default for weekly time-series analysis.

iso_week ISO 8601 week series (Monday–Sunday weeks; week 1 is the week containing January 4).
When this option is used, survcollapse outputs ISO-consistent year and week.

cdc_week CDC/MMWR epidemiologic week series (Sunday–Saturday weeks; week 1 is the first week
with at least four days in January). When this option is used, survcollapse outputs CDC/MMWR-consistent
year and week.

saving(filename) specifies the user-defined name of the output dataset to be saved.
Use replace to overwrite an existing file.

Optional

keepvars(varlist) specifies identifier variables (e.g., country, province, region, sex/gender,
age group, case definition, etc.) to be retained in the output dataset. These variables do not define panels
for collapsing; survcollapse collapses by timevar() only. Therefore, variables in keepvars()
must be constant within the if/in sample. If keepvars() includes a variable whose values vary
within the selected sample, survcollapse may fail. keepvars() may be omitted and survcollapse
will still run. However, when subsetting with if/in, including the corresponding identifier variable(s)
in keepvars() ensures they are retained in the output dataset.

replace allows overwriting the file specified in saving().

Output

The saved dataset contains (at minimum) the following variables:

casevar summed cases for the user-selected timevar() unit.

created indicator for filled-in time units: 1 if the time unit was created by survcollapse, 0 if it existed in the data prior to collapsing.

Output time variables depend on timevar():

If timevar(__day) is used, the output includes __day (daily Stata date).

If a weekly option is used the output includes year and week, where week follows the selected weekly definition.

If keepvars() is specified, those variables are included in the output as constants.

Notes

The output dataset is completed over the range [min(time), max(time)] of the selected time unit. Missing
time units are created and assigned 0 cases and flagged with created = 1.

If collapsing a single national series without a variable corresponding to country, the user should create
one before running the program (e.g., gen byte country = 1) and then use keepvars(country).

If set varabbrev off is in effect, option arguments must use full variable names.

Examples

A common use is to convert case-level (line-list) data—often with multiple observations per day—into a
collapsed daily time series (one observation per day with one or more cases). Case-level data or a
collapsed daily time series can then be aggregated into weekly or monthly totals. For example, collapse
to one observation per day (filling missing days between the minimum and maximum observed day) and save
the resulting dataset:

survcollapse, datevar(date) casevar(cases) timevar(__day) keepvars(country) saving(temp1.dta) replace

Aggregate the daily series to ISO epidemiologic weeks and save the weekly dataset:

survcollapse, datevar(__day) casevar(cases) timevar(iso_week) keepvars(country) saving(temp2.dta) replace

Collapse data for a single state:

survcollapse if state==1, datevar(date) casevar(cases) timevar(iso_week) keepvars(state) saving(temp_state1_week.dta) replace

Collapse laboratory-confirmed cases for a single state:

survcollapse if state==10 & tested==1, datevar(date) casevar(cases) timevar(iso_week) keepvars(state tested) saving(temp_state1_tested1_week.dta) replace

To obtain monthly totals, create a month identifier from the daily date and then collapse using that
month variable. Re-collapsing weekly data to months is not recommended because weeks do not align with
calendar months (weeks may overlap two months). For example:

gen month = mofd(__day)

format month %tm

survcollapse, datevar(__day) casevar(cases) timevar(month) keepvars(country) saving(temp3.dta) replace

Stored results

None.

Author

Leonelo Bautista

University of Wisconsin-Madison

Department of Population Health Sciences

lebautista@wisc.edu

v1.0 17Jan2026

Also see

collapse, tsfill, fillin, wofd, yw