umx (version 1.2.7)

umxThresholdMatrix: umxThresholdMatrix

Description

High-level helper for ordinal modeling. Creates, labels, and sets smart-starts for this complex matrix. Big time saver!

Usage

umxThresholdMatrix(df, suffixes = NA, threshMatName = "threshMat", method = c("auto", "Mehta", "allFree"), l_u_bound = c(NA, NA), deviationBased = TRUE, droplevels = FALSE, verbose = FALSE, hint = c("none", "left_censored"))

Arguments

df

the data being modelled (to allow access to the factor levels and quantiles within these for each variable)

suffixes

e.g. c("T1", "T2") - Use for data with repeated observations in a row (i.e., twin data) (defaults to NA)

threshMatName

name of the matrix which is returned. Defaults to "threshMat" - best not to change it.

method

How to set the thresholds: auto (the default), Mehta, which fixes the first two (auto chooses this for ordinal) or "allFree" (auto chooses this for binary)

l_u_bound

c(NA, NA) by default, you can use this to bound the thresholds. Careful you don't set bounds too close if you do.

deviationBased

Whether to build a helper matrix to keep the thresholds in order (defaults to = TRUE)

droplevels

Whether to drop levels with no observed data (defaults to FALSE)

verbose

(defaults to FALSE))

hint

currently used for "left_censored" data (defaults to "none"))

Value

- thresholds matrix

Details

When modeling ordinal data (sex, low-med-hi, depressed/normal, not at all, rarely, often, always), a useful conceptual strategy to handle expectations is to build a standard-normal model (i.e., a latent model with zero-means, and unit (1.0) variances), and then to threshold this normal distribution to generate the observed data. Thus an observation of "depressed" is modeled as a high score on the latent normally distributed trait, with thresholds set so that only scores above this threshold (1-minus the number of categories).

For deviation methods, it returns a list of lowerOnes_for_thresh, deviations_for_thresh & thresholdsAlgebra (named threshMatName)

For direct, it returns a thresholdsMatrix (named threshMatName)

References

- http://tbates.github.io, https://github.com/tbates/umx

See Also

Other Model Building Functions: umxDiagnose, umxLabel, umxLatent, umxModify, umxPath, umxRAM, umxRun, umxValues, umx_fix_first_loadings, umx_fix_latents, umx

Examples

x = data.frame(ordered(rbinom(100,1,.5))); names(x) <- c("x")
umxThresholdMatrix(x)
x = cut(rnorm(100), breaks = c(-Inf,.2,.5, .7, Inf)); levels(x) = 1:5
x = data.frame(ordered(x)); names(x) <- c("x")
tm = umxThresholdMatrix(x)

# ==================
# = Binary example =
# ==================
require(umx)
data(twinData)
labList = c("MZFF", "MZMM", "DZFF", "DZMM", "DZOS")
twinData$zyg = factor(twinData$zyg, levels = 1:5, labels = labList)
# Cut to form category of 80 % obese subjects
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) 
# Step 2: Make the ordinal variables into mxFactors
# this ensures ordered= TRUE + requires user to confirm levels
selDVs = c("obese1", "obese2")
twinData[, selDVs] <- mxFactor(twinData[, selDVs], levels = obesityLevels)
mzData <- subset(twinData, zyg == "MZFF", selDVs)
str(mzData)
tm = umxThresholdMatrix(mzData, suffixes = 1:2, verbose = TRUE) # informative messages

# ======================================
# = Ordinal (n categories > 2) example =
# ======================================
# Cut to form three categories of weight
cutPoints <- quantile(twinData[, "bmi1"], probs = c(.4, .7), na.rm = TRUE)
obesityLevels = c('normal', 'overweight', 'obese')
twinData$obeseTri1 <- cut(twinData$bmi1, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
twinData$obeseTri2 <- cut(twinData$bmi2, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
selDVs = c("obeseTri1", "obeseTri2")
twinData[, selDVs] <- mxFactor(twinData[, selDVs], levels = obesityLevels)
mzData <- subset(twinData, zyg == "MZFF", selDVs)
str(mzData)
tm = umxThresholdMatrix(mzData, suffixes = 1:2, verbose = TRUE)

# ========================================================
# = Mix of all three kinds example (and a 4-level trait) =
# ========================================================

cutPoints <- quantile(twinData[, "bmi1"], probs = c(.25, .4, .7), na.rm = TRUE)
obesityLevels = c('underWeight', 'normal', 'overweight', 'obese')
twinData$obeseQuad1 <- cut(twinData$bmi1, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
twinData$obeseQuad2 <- cut(twinData$bmi2, breaks = c(-Inf, cutPoints, Inf), labels = obesityLevels) 
selDVs = c("obeseQuad1", "obeseQuad2")
twinData[, selDVs] <- mxFactor(twinData[, selDVs], levels = obesityLevels)

selDVs = umx_paste_names(c("bmi", "obese", "obeseTri", "obeseQuad"), "", 1:2)
mzData <- subset(twinData, zyg == "MZFF", selDVs)
str(mzData)
tm = umxThresholdMatrix(mzData, suffixes = 1:2, verbose = TRUE)

# ===================
# = "left_censored" =
# ===================

x = round(10 * rnorm(1000, mean = -.2))
x[x < 0] = 0
x = mxFactor(x, levels = sort(unique(x)))
x = data.frame(x)
# umxThresholdMatrix(x, deviation = FALSE, hint = "left_censored")