xmu_make_TwinSuperModel {umx}R Documentation

Helper to make a basic top, MZ, and DZ model.

Description

xmu_make_TwinSuperModel makes basic twin model containing top, MZ, and DZ models. It intelligently handles thresholds for ordinal data, and means model for covariates matrices in the twin models if needed.

It's the replacement for xmu_assemble_twin_supermodel approach.

Usage

xmu_make_TwinSuperModel(
  name = "twin_super",
  mzData,
  dzData,
  selDVs,
  selCovs = NULL,
  sep = NULL,
  type = c("Auto", "FIML", "cov", "cor", "WLS", "DWLS", "ULS"),
  allContinuousMethod = c("cumulants", "marginals"),
  numObsMZ = NULL,
  numObsDZ = NULL,
  nSib = 2,
  equateMeans = TRUE,
  weightVar = NULL,
  bVector = FALSE,
  dropMissingDef = TRUE,
  verbose = FALSE
)

Arguments

name

for the supermodel

mzData

Dataframe containing the MZ data

dzData

Dataframe containing the DZ data

selDVs

List of manifest base names (e.g. BMI, NOT 'BMI_T1') (OR, you don't set "sep", the full variable names)

selCovs

List of covariate base names (e.g. age, NOT 'age_T1') (OR, you don't set "sep", the full variable names)

sep

string used to expand selDVs into selVars, i.e., "_T" to expand BMI into BMI_T1 and BMI_T2 (optional but STRONGLY encouraged)

type

One of 'Auto','FIML','cov', 'cor', 'WLS','DWLS', or 'ULS'. Auto tries to react to the incoming mxData type (raw/cov).

allContinuousMethod

"cumulants" or "marginals". Used in all-continuous WLS data to determine if a means model needed.

numObsMZ

Number of MZ observations contributing (for summary data only)

numObsDZ

Number of DZ observations contributing (for summary data only)

nSib

Number of members per family (default = 2)

equateMeans

Whether to equate T1 and T2 means (default = TRUE).

weightVar

If provided, a vector objective will be used to weight the data. (default = NULL).

bVector

Whether to compute row-wise likelihoods (defaults to FALSE).

dropMissingDef

Whether to automatically drop missing def var rows for the user (default = TRUE). You get a polite note.

verbose

(default = FALSE)

Details

xmu_make_TwinSuperModel is used in twin models (e.g.umxCP(), umxACE() and umxACEv() and will be added to the other models: umxGxE(), umxIP(), simplifying code maintenance.

It takes mzData and dzData, a list of the selDVs to analyse and optional selCovs (as well as sep and nSib), along with other relevant information such as whether the user wants to equateMeans. It can also handle a weightVar.

If covariates are passed in these are included in the means model (via a call to xmuTwinUpgradeMeansToCovariateModel.

Modeling

Matrices created

top model

For raw and WLS data, top contains a expMeans matrix (if needed). For summary data, the top model contains only a name.

For ordinal data, top gains top.threshMat (from a call to umxThresholdMatrix()).

For covariates, top stores the intercepts matrix and a betaDef matrix. These are then used to make expMeans in MZ and DZ.

MZ and DZ models

MZ and DZ contain the data, and an expectation referencing top.expCovMZ and top.expMean, and, vector = bVector. For continuous raw data, MZ and DZ contain OpenMx::mxExpectationNormal() and OpenMx::mxFitFunctionML(). For WLS these the fit function is switched to OpenMx::mxFitFunctionWLS() with appropriate type and allContinuousMethod.

For binary, a constraint and algebras are included to constrain Vtot (A+C+E) to 1.

If a weightVar is detected, these columns are used to create a row-weighted MZ and DZ models.

If equateMeans is TRUE, then the Twin-2 vars in the mean matrix are equated by label with Twin-1.

Decent starts are guessed from the data. varStarts is computed as sqrt(variance)/3 of the DVs and meanStarts as the variable means. For raw data, a check is made for ordered variables. For Binary variables, means are fixed at 0 and total variance (A+C+E) is fixed at 1. For ordinal variables, the first 2 thresholds are fixed.

Where needed, e.g. continuous raw data, top adds a means matrix "expMean". For ordinal data, top adds a umxThresholdMatrix().

If binary variables are present, matrices and a constraint to hold A+C+E == 1 are added to top.

If a weight variable is offered up, an mzWeightMatrix will be added.

Data handling

In terms of data handling, xmu_make_TwinSuperModel was primarily designed to take data.frames and process these into mxData. It can also, however, handle cov and mxData input.

It can process data into all the types supported by mxData.

Raw data input with a target of cov or cor type requires the numObsMZ and numObsDZ to be set.

Type "WLS", "DWLS", or "ULS", data remain raw, but are handled as WLS in the OpenMx::mxFitFunctionWLS().

Unused columns are dropped.

If you pass in raw data, you can't request type cov/cor yet. Will work on this if desired.

Value

See Also

Other xmu internal not for end user: umxModel(), umxRenameMatrix(), umx_APA_pval(), umx_fun_mean_sd(), umx_get_bracket_addresses(), umx_make(), umx_standardize(), umx_string_to_algebra(), xmuHasSquareBrackets(), xmuLabel_MATRIX_Model(), xmuLabel_Matrix(), xmuLabel_RAM_Model(), xmuMI(), xmuMakeDeviationThresholdsMatrices(), xmuMakeOneHeadedPathsFromPathList(), xmuMakeTwoHeadedPathsFromPathList(), xmuMaxLevels(), xmuMinLevels(), xmuPropagateLabels(), xmuRAM2Ordinal(), xmuTwinSuper_Continuous(), xmuTwinSuper_NoBinary(), xmuTwinUpgradeMeansToCovariateModel(), xmu_CI_merge(), xmu_CI_stash(), xmu_DF_to_mxData_TypeCov(), xmu_PadAndPruneForDefVars(), xmu_bracket_address2rclabel(), xmu_cell_is_on(), xmu_check_levels_identical(), xmu_check_needs_means(), xmu_check_variance(), xmu_clean_label(), xmu_data_missing(), xmu_data_swap_a_block(), xmu_describe_data_WLS(), xmu_dot_make_paths(), xmu_dot_make_residuals(), xmu_dot_maker(), xmu_dot_move_ranks(), xmu_dot_rank_str(), xmu_extract_column(), xmu_get_CI(), xmu_lavaan_process_group(), xmu_make_bin_cont_pair_data(), xmu_make_mxData(), xmu_match.arg(), xmu_name_from_lavaan_str(), xmu_path2twin(), xmu_path_regex(), xmu_print_algebras(), xmu_rclabel_2_bracket_address(), xmu_safe_run_summary(), xmu_set_sep_from_suffix(), xmu_show_fit_or_comparison(), xmu_simplex_corner(), xmu_standardize_ACEcov(), xmu_standardize_ACEv(), xmu_standardize_ACE(), xmu_standardize_CP(), xmu_standardize_IP(), xmu_standardize_RAM(), xmu_standardize_SexLim(), xmu_standardize_Simplex(), xmu_start_value_list(), xmu_starts(), xmu_summary_RAM_group_parameters(), xmu_twin_add_WeightMatrices(), xmu_twin_check(), xmu_twin_get_var_names(), xmu_twin_make_def_means_mats_and_alg(), xmu_twin_upgrade_selDvs2SelVars()

Examples

# ==============
# = Continuous =
# ==============
library(umx)
data(twinData)
twinData = umx_scale(twinData, varsToScale= c('ht1','ht2'))
mzData = twinData[twinData$zygosity %in%  "MZFF",] 
dzData = twinData[twinData$zygosity %in%  "DZFF",]
m1= xmu_make_TwinSuperModel(mzData=mzData, dzData=dzData, selDVs=c("wt","ht"), sep="", nSib=2)
names(m1) # "top" "MZ"  "DZ"
class(m1$MZ$fitfunction)[[1]] == "MxFitFunctionML"

# ====================
# = With a covariate =
# ====================

m1= xmu_make_TwinSuperModel(mzData=mzData, dzData=dzData, 
		selDVs= "wt", selCovs= "age", sep="", nSib=2)
m1$top$intercept$labels
m1$MZ$expMean

# ===============
# = WLS example =
# ===============
m1=xmu_make_TwinSuperModel(mzData=mzData, dzData=dzData,selDVs=c("wt","ht"),sep="",type="WLS")
class(m1$MZ$fitfunction)[[1]] == "MxFitFunctionWLS"
m1$MZ$fitfunction$type =="WLS"
# Check default all-continuous method
m1$MZ$fitfunction$continuousType == "cumulants"

# Choose non-default type (DWLS)
m1= xmu_make_TwinSuperModel(mzData= mzData, dzData= dzData,
	selDVs= c("wt","ht"), sep="", type="DWLS")
m1$MZ$fitfunction$type =="DWLS"
class(m1$MZ$fitfunction)[[1]] == "MxFitFunctionWLS"

# Switch WLS method
m1 = xmu_make_TwinSuperModel(mzData= mzData, dzData= dzData, selDVs= c("wt","ht"), sep= "",
  type = "WLS", allContinuousMethod = "marginals")
m1$MZ$fitfunction$continuousType == "marginals"
class(m1$MZ$fitfunction)[[1]] == "MxFitFunctionWLS"


# ============================================
# = Bivariate continuous and ordinal example =
# ============================================
data(twinData)
selDVs = c("wt", "obese")
# Cut BMI column to form ordinal obesity variables
ordDVs          = c("obese1", "obese2")
obesityLevels   = c('normal', 'overweight', 'obese')
cutPoints       = quantile(twinData[, "bmi1"], probs = c(.5, .2), na.rm = TRUE)
twinData$obese1 = cut(twinData$bmi1, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
twinData$obese2 = cut(twinData$bmi2, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
# Make the ordinal variables into mxFactors (ensure ordered is TRUE, and require levels)
twinData[, ordDVs] = umxFactor(twinData[, ordDVs])
mzData = twinData[twinData$zygosity %in%  "MZFF",] 
dzData = twinData[twinData$zygosity %in%  "DZFF",]
m1 = xmu_make_TwinSuperModel(mzData= mzData, dzData= dzData, selDVs= selDVs, sep="", nSib= 2)
names(m1) # "top" "MZ"  "DZ" 

# ==============
# = One binary =
# ==============
data(twinData)
cutPoints       = quantile(twinData[, "bmi1"], probs = .2, na.rm = TRUE)
obesityLevels   = c('normal', 'obese')
twinData$obese1 = cut(twinData$bmi1, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
twinData$obese2 = cut(twinData$bmi2, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
ordDVs = c("obese1", "obese2")
twinData[, ordDVs] = umxFactor(twinData[, ordDVs])
selDVs = c("wt", "obese")
mzData = twinData[twinData$zygosity %in% "MZFF",]
dzData = twinData[twinData$zygosity %in% "DZFF",]
m1 = xmu_make_TwinSuperModel(mzData= mzData, dzData= dzData, selDVs= selDVs, sep= "", nSib= 2)

# ========================================
# = Cov data (calls xmuTwinSuper_CovCor) =
# ========================================

data(twinData)
mzData =cov(twinData[twinData$zygosity %in% "MZFF", tvars(c("wt","ht"), sep="")], use="complete")
dzData =cov(twinData[twinData$zygosity %in% "DZFF", tvars(c("wt","ht"), sep="")], use="complete")
m1 = xmu_make_TwinSuperModel(mzData= mzData, dzData= dzData, selDVs= "wt", sep= "", 
	nSib= 2, numObsMZ = 100, numObsDZ = 100, verbose=TRUE)
class(m1$MZ$fitfunction)[[1]] =="MxFitFunctionML"
dimnames(m1$MZ$data$observed)[[1]]==c("wt1", "wt2")
[Package umx version 4.20.0 Index]