createOnset: Returns data.table of binary, up-only 'onset' variables x...
In johninpdx/RSTools: Data Mangement Tools for RSiena and Other Network Packages

Description Usage Arguments Details Value Note Examples

This is a stand-alone scoring function that takes a wide-form data.table or dataframe of 'lifetime use' variables for a (presumably consecutive) set of waves, and transforms them into up-only variables with the value 1 when the participant first reports any lifetime use.

1	createOnset(pInDT, pTHold = 1)

`pInDT`	A data.table (or dataframe) containing SID plus a lifetime use (NA, 0, >0) variable for each of c-1 ordered time periods, where c is the number of columns in the DF.
`pTHold`	The threshold (numerical value) for lifetime use; if the input use variable value is >= pTHold, then the event 'occurred'.

The logic assigns 1's to the output variables for all waves after the first *known* positive instance (KPI; value >= pTHold) of the event. It also ignores instances where a participant reports the event at wave w, but then does not report any lifetime use at some wave w+k. Instead, the value of the onset variable will be 1 from the first instance of the event on. For waves prior to the KPI, NAs are changed to 0 if they preceded a non-KPI event (value < pTHold), but left as NAs otherwise.

A data.table of the same dimension as the input data table, with rows transformed into up-only variables suitable for use in proportional hazard models, or onset/rate models (in RSiena).

The effect of this coding logic is as follows: (a) If the 'onset' variable is NA for either wave w or wave w+1, then that individual will be included in target statistics for onset between those two waves, but with a value equal to the overall mean (typically 0, since the variable will be centered). (b) The individual will participate in the simulations, with the assumption that the missing value had the sample mean value at whichever wave it was missing.

# Returns a table of up-only variables which have the value 0 before the
# first known lifetime alcohol use (if any such times are available), and 1
# thereafter. The pTHold value of 1 means *any* use.
# Get network 'Analysis Set'; last list element is unique SIDs
netList <- getNetworkSet(pWavVec = c(1,3,4), pSchVec = c(3,4,5,6,30))
# Get table of TVCs for these waves and schools
ccTbl <- getNQTVCs(pWavVec = c(1,3,4), pSchVec = c(3,4,5,6,30))
# Make TVC table for 'lifetime alc freq of use'
alcLife <- makeTVTbl(ccTbl, netList[[4]], pVar = "AL",
    pCut = c(0, .5, 1, 5, 20), pMaxNA = 3)
# Create onset variable
alcOnset <- createOnset(alcLife,pTHold = 1)