umx_make_double_entry_data: Prepare data for Double-Entry Censored Twin Models

In umx: Structural Equation Modeling and Twin Modeling in R

Prepare data for Double-Entry Censored Twin Models

Description

Helper to split one or more variables in a twin dataset into a paired continuous column (holding non-censored values) and an ordered factor column (indicating censoring status), ready for umxACE_DE.

The function has flexible rules for censoring. You give a list() of columns, with the censoring rule for each, and the function creates new matching var_cens and var_cont columns. A rule can be a simple numeric value to cut at, e.g., list(wt=0)) for cut column wt at zero. More complex expressions should be in quotes list(wt="<= cut"). Mutual-NA invariant enforced: Each row contributes exactly one non-missing element per DE trait - continuous density f(x) or threshold CDF P(Y \le \tau) - preventing double-counting. On non-censored rows, the function sets the var_cont to the observed value and the var_cens value to NA. On censored rows, the continuous column is set to NA, and the correct value of an ordered factor c("censored","observed") is set in var_cens (integer 1). Right-censor ⁠>=cut⁠ flips levels to c("observed","censored") so censored = integer 2 (upper tail). NA in raw propagates to NA in both.

Usage

umx_make_double_entry_data(
  data,
  cols = NULL,
  doubleEntrySuffix = c("_cont", "_cens"),
  sep = "_T",
  nSib = 2,
  levels = NULL
)

Arguments

data	The dataframe to process.
cols	A named list of variables and their censoring rules. A numeric scalar is left-censoring at that floor; length-2 numeric is interval; character comparison (e.g. "<= 0", ">= 40") or a function are also allowed. Known finite bounds are stored in attribute umxDoubleEntry for optional use by umxACE_DE() with fixCensorThresholds = "auto" or "yes".
doubleEntrySuffix	Suffixes for the continuous and censored columns (default = c("_cont", "_cens")).
sep	Suffix/separator for twin indices (default = "_T").
nSib	Number of siblings/twins (default = 2).
levels	Ordered factor levels for the censored column. NULL (default) chooses by censor side: left/interval/unknown use c("censored", "observed"); right uses c("observed", "censored"). If supplied, must include the level name "censored" (assigned by name when censored, never by index alone).

Details

Double-entry data preparation creates paired continuous (_cont) and ordinal factor (_cens) columns for censored traits.

To prevent likelihood double-counting during FIML estimation:

• Non-censored observations (x > cut) retain their numeric continuous score in _cont, while _cens is set to NA.

• Censored observations (x \le cut) have _cont set to NA, while _cens records the ordinal censored status level.

This ensures each case contributes exactly one mutually exclusive likelihood component (either continuous PDF or ordinal CDF threshold probability).

Value

The modified dataframe with expanded double-entry pairs and attribute umxDoubleEntry listing per-trait cut, side, and whether the cut is fixable in a model.

See Also

• umxACE_DE(), umxRAM_DE(), plot(), umxSummary(), umxModify(), umxCompare()

Other Twin Modeling Functions: power.ACE.test(), umx, umxACE(), umxACE_DE(), umxACE_GLM(), umxACEcov(), umxACEv(), umxCP(), umxCloud(), umxDiffMZ(), umxDiscTwin(), umxDoC(), umxDoCp(), umxGxE(), umxGxE_window(), umxGxEbiv(), umxIP(), umxMRDoC(), umxReduce(), umxReduceACE(), umxReduceGxE(), umxRotate.MxModelCP(), umxSexLim(), umxSimplex(), umxSummarizeTwinData(), umxSummaryACE(), umxSummaryACE_GLM(), umxSummaryACEv(), umxSummaryDoC(), umxSummaryGxEbiv(), umxSummarySexLim(), umxSummarySimplex(), umxTwinMaker()

Examples

## Not run: 
data(twinData)
prep = umx_make_double_entry_data(twinData, cols = list(wt = 0), sep = "")
# attr(prep, "umxDoubleEntry")$pairs[[1]]$cut  # 0

# Then
selDVs = c("ht", "wt_cont", "wt_cens")
# Known LOD
umxACE_DE(data = prep, selDVs = selDVs, sep = "")
# Un-known LOD
umxACE_DE(data = prep, selDVs = selDVs, sep = "", fixCensorThresholds = "no")
# Mix with continuous traits:
umxACE_DE(data = prep, selDVs = c("ht", "wt_cont", "wt_cens"))

## End(Not run)

umx documentation built on Oct. 11, 2026, 5:07 p.m.