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

Description Usage Arguments Value See Also Examples

View source: R/xmu_make_top_twin_models.R

Description

xmu_make_top_twin makes basic top, MZ, and DZ models. It includes thresholds matrices in the twin models if needed.

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

xmu_make_top_twin takes mzData and dzData, a list of the selDVs to analyse (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.

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.

Modeling

top model

For raw and WLS data, top contains a means 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()).

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, this column is added to mzWeightMatrix/mzWeightMatrix.

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

Matrices created

Decent starts are guessed from the data. 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_top_twin 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.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
xmu_make_top_twin(
  mzData,
  dzData,
  selDVs,
  selCovs = NULL,
  sep = NULL,
  type = c("Auto", "FIML", "cov", "cor", "WLS", "DWLS", "ULS"),
  allContinuousMethod = c("cumulants", "marginals"),
  nSib = 2,
  numObsMZ = NULL,
  numObsDZ = NULL,
  equateMeans = TRUE,
  weightVar = NULL,
  bVector = FALSE,
  verbose = FALSE
)

Arguments

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.

nSib

Number of members per family (default = 2)

numObsMZ

Number of MZ observations contributing (for summary data only)

numObsDZ

Number of DZ observations contributing (for summary data only)

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).

verbose

(default = FALSE)

Value

See Also

Other xmu internal not for end user: umxModel(), umxTwinMaker(), umx_APA_pval(), umx_fun_mean_sd(), umx_get_bracket_addresses(), umx_make(), umx_standardize(), umx_string_to_algebra(), umx, xmuDefBetasInTop(), xmuDefMeanInDataGroup(), xmuHasSquareBrackets(), xmuLabel_MATRIX_Model(), xmuLabel_Matrix(), xmuLabel_RAM_Model(), xmuMI(), xmuMakeDeviationThresholdsMatrices(), xmuMakeOneHeadedPathsFromPathList(), xmuMakeTwoHeadedPathsFromPathList(), xmuMaxLevels(), xmuMinLevels(), xmuPropagateLabels(), xmuRAM2Ordinal(), xmu_CI_merge(), xmu_CI_stash(), xmu_DF_to_mxData_TypeCov(), xmu_PadAndPruneForDefVars(), xmu_assemble_twin_supermodel(), xmu_cell_is_on(), xmu_check_levels_identical(), xmu_check_needs_means(), xmu_check_variance(), xmu_clean_label(), 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_get_CI(), xmu_lavaan_process_group(), xmu_make_TwinSuperModel(), xmu_make_bin_cont_pair_data(), xmu_make_mxData(), xmu_match.arg(), xmu_name_from_lavaan_str(), xmu_path2twin(), xmu_path_regex(), 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_twin_check()

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# ==============
# = Continuous =
# ==============
library(umx)
data(twinData)
selDVs = c("wt", "ht")
mzData = twinData[twinData$zygosity %in%  "MZFF",] 
dzData = twinData[twinData$zygosity %in%  "DZFF",]
bits = xmu_make_top_twin(mzData= mzData, dzData= dzData, selDVs= selDVs, sep= "", nSib= 2)
names(bits) # "top" "MZ"  "DZ" "bVector" "mzWeightMatrix" "dzWeightMatrix"
class(bits$MZ$fitfunction)[[1]] == "MxFitFunctionML"

bits = xmu_make_top_twin(mzData= mzData, dzData= dzData, 
	selDVs= selDVs, sep= "", type = "WLS")
class(bits$MZ$fitfunction)[[1]] == "MxFitFunctionWLS"
bits$MZ$fitfunction$type =="WLS"
bits$MZ$fitfunction$continuousType == "cumulants"

# Choose non-default type (DWLS)
bits = xmu_make_top_twin(mzData= mzData, dzData= dzData,
	selDVs = selDVs, sep= "", type = "DWLS")
bits$MZ$fitfunction$type =="DWLS"
class(bits$MZ$fitfunction)[[1]] == "MxFitFunctionWLS"

# Switch continuous method
bits = xmu_make_top_twin(mzData= mzData, dzData= dzData, selDVs= selDVs, sep= "",
	type = "WLS", allContinuousMethod = "marginals")
bits$MZ$fitfunction$continuousType == "marginals"
class(bits$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",]
bits = xmu_make_top_twin(mzData= mzData, dzData= dzData, selDVs= selDVs, sep="", nSib= 2)
names(bits) # "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",]
bits = xmu_make_top_twin(mzData= mzData, dzData= dzData, selDVs= selDVs, sep= "", nSib= 2)

# ============
# = Cov data =
# ============
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")
bits = xmu_make_top_twin(mzData= mzData, dzData= dzData, selDVs= "wt", sep= "", nSib= 2, numObsMZ = 100, numObsDZ = 100, verbose=TRUE)
class(bits$MZ$fitfunction)[[1]] =="MxFitFunctionML"
names(bits$MZ$data$observed) == c("wt1", "wt2") # height columns dropped

tbates/umx documentation built on March 30, 2020, 7:56 a.m.