*! version 1.1 04jan2017

Title

pc_bootstrap_units -- Program to simulate additional units, in order to conduct power calculations by simulation using pc_simulate

Syntax

pc_bootstrap_units panelvar [if] [in] , nunits(#) [varlist(varlist) sort(varlist)]

Required
nunits(#) desired number of cross-sectional units (unique values of panelvar),
or the number of existing units plus the number of simulated units to be bootstrapped; must be a positive integer.

Optional
varlist(varlist) subset of variables to be bootstrapped; if not specified, program will copy all variables in dataset to simulated units.

sort(varlist) list of variables to sort by, before bootstrapping simulated units;
if not specified, program will not sort by variables other than panelvar.

Description

This program adds cross-sectional units to an existing dataset, for the purposes of facilitating power calculations using pc_simulate. It
creates new "simulated" units by drawing with replacement from existing units in the dataset.

pc_bootstrap_units allows users to simulate power calculations for experiments with samples sizes larger than their existing datasets. By
bootstrapping "simulated" units from existing sample units, it assumes that these sample units are representative of the full population. It
also ensures that the outcome variable (depvar) exhibits the same variance-covariance structure in both real and simulated units.

Details

The program first calculates the number (nexisting) of unique values of panelvar. Then,
for each additional unit to be bootstrapped, it randomly chooses one of the nexisting original units
and appends all of this unit's observations to the bottom of the dataset. It
repeats this process until the total number of units equals nunits.

If the dataset is unique by panelvar (i.e. not a 2-dimensional panel, but suitable for a cross-sectional ONESHOT power calculation),
each bootstrapped unit will only add 1 new row to the dataset.

The program assigns a new value of panelvar for each simulated unit, in order to distinguish it from existing units. It
also creates a new variable, ORIGpanelvar, which stores each bootstrapped unit's original panelvar value. ORIGpanelvar
is missing for all nexisting original units, and populated for all bootstrapped units.

For large datasets, users may only wish to populate certain variables to the simulated units (i.e. only variables to be used by pc_simulate).
The option varlist(varlist) allows users to select which variables to populate.

The option sort(varlist) allows users to sort along a second panel dimension,
in order to improve readability. For
example, sort(timevar) yields a final dataset sorted by panelvar timevar, with existing units on top, bootstrapped units on the bottom, and the observations within each unit sorted by time period.

Example

Suppose the existing dataset is a two-dimensional panel containing 40 unique cross-sectional units, numbered person_id = {1,...,40}. Suppose each unit has 15 time-period observations.

The following command would allow pc_simulate to perform power calculations for an experiment with 60 units:

. pc_bootstrap_units person_id, nunits(60)

The resulting dataset would contain 300 new observations for 20 simulated units, numbered person_id = {41,...,60}. Each
new observation would contain 15 time periods, and would simply duplicate one of the original 40 observations.

The new variable ORIGperson_id would be missing for all original units, and would be populated for all simulated units, indicating the original unit from which each simulated unit was bootstrapped.

Contact

Louis Preonas

Department of Agricultural and Resource Economics

Energy Institute at Haas

UC Berkeley

Email: lpreonas@berkeley.edu

This program is part of the ssc package pcpanel.