expand_periods: Expand observations across periods

In simulab: Simulates a Wide Variety of Data Shapes, Sizes and Distributions

Expand observations across periods

Description

Repeats every unit's row once per period, numbering the periods and adding the elapsed time each period falls at. Units may be followed for different numbers of periods, and the spacing may be regular or irregular. A set of wide columns, one per period, can be gathered into a single long value column at the same time.

Usage

expand_periods(
  data,
  periods = NULL,
  id = "id",
  period = "period",
  period_values = NULL,
  interval_mean = NULL,
  interval_dispersion = 0,
  time = "time",
  time_variables = NULL,
  value = "value",
  seed = NULL
)

Arguments

data	Base data.frame, or a simulab_sim, with one row per observational unit and at least one row.
periods	Number of periods: a single whole number applied to every unit, the name of a column of data holding a count per unit, or NULL when period_values is supplied.
id	Identifier variable. A single string naming a column of data. It is carried into the schedule component; the returned rows are the input rows repeated, so the identifier is not renumbered.
period	Name of the period column. A single non-empty string, defaulting to "period". Periods generated from periods are numbered from 0, so a unit followed for k periods gets 0 to k - 1.
period_values	Optional atomic vector of period values shared by every unit, used in place of the numbering above. Defaults to NULL, and may not be combined with periods.
interval_mean	Mean interval between consecutive periods: a single number, the name of a column of data, or NULL (the default) for an interval of 1.
interval_dispersion	Dispersion of the gamma-distributed intervals: a single non-negative number, or the name of a column of data. Defaults to 0, exactly regular spacing; a positive value draws each interval from a gamma distribution with mean interval_mean and variance interval_mean^2 * interval_dispersion.
time	Name of the generated elapsed-time column, which starts at 0 for every unit and accumulates the intervals. A single string, defaulting to "time".
time_variables	Optional character vector of wide columns of data, exactly one per period, gathered into the long value column and then dropped. Defaults to NULL.
value	Name of the gathered time-varying value. A single non-empty string, defaulting to "value".
seed	Optional random seed for irregular intervals. A single number, or NULL (the default).

Value

A simulab_sim base data.frame with one row per unit-period, holding the columns of data plus the period and elapsed-time columns, and the gathered value column in place of time_variables when those are given. The component schedule, reached with as.data.frame(x, what = "schedule"), holds one row per input unit with columns input_row, id, periods, interval_mean and interval_dispersion.

Examples

data <- data.frame(id = 1:10)
result <- expand_periods(data, periods = 4, id = "id", period = "period")
head(result)

simulab documentation built on Oct. 15, 2026, 5:08 p.m.