umx (version 4.20.0)

umx_names: umx_names

Description

Convenient equivalent of running grep on names, with value = TRUE and ignore.case = TRUE.

Plus:umx_names can handle dataframes, a model, list of models, model summary, or a vector of strings as input.

In these cases, it will search column names, parameter or summary output names, or the literal string values themselves respectively.

In addition, umx_names can do replacement of a found string (see examples). It can also collapse the result (using paste0)

Note: namez (with a z) is a shortcut for umx_names, which makes it easy to replace where you would otherwise use names.

You can learn more about the matching options (like inverting the selection etc.) in the help for base-R grep.

Usage

umx_names(
  df,
  pattern = ".*",
  replacement = NULL,
  ignore.case = TRUE,
  perl = FALSE,
  value = TRUE,
  fixed = FALSE,
  useBytes = FALSE,
  invert = FALSE,
  global = FALSE,
  collapse = c("as.is", "vector", "formula")
)

Value

• vector of matches

Arguments

df

dataframe (or other objects, or a list of models) from which to get names.

pattern

Used to find only matching names (supports grep/regular expressions)

replacement

If not NULL, replaces the found string. Use backreferences ("\1" to "\9") to refer to (subexpressions).

ignore.case

default = TRUE (opposite default to grep)

perl

Should Perl-compatible regexps be used? Default = FALSE

value

Return matching elements themselves (TRUE) or their indices (FALSE) default = TRUE (opposite default to grep)

fixed

= FALSE (grep option If TRUE, pattern is a string to be matched as is. Overrides all conflicting arguments.)

useBytes

= FALSE logical. grep option. If TRUE, matching is by byte rather than by character.

invert

Return indices or values for elements that do not match (default = FALSE).

global

replace all instances in each strong, or just the first (Default).

collapse

"as.is" leaves alone. as.vector formats as pasteable code, i.e., "c('a', 'b')", not "a" "b" (default NULL), etc.

References

• https://tbates.github.io, https://github.com/tbates/umx

See Also

• Base-R pattern matching functions: grep(). And umx_check_names() to check for existence of names in a dataframe.

Other String Functions: umx_explode_twin_names(), umx_explode(), umx_grep(), umx_paste_names(), umx_rot(), umx_str_chars(), umx_str_from_object(), umx_trim(), umx

Examples

# Names from a dataframe, with character matching
umx_names(mtcars, "mpg") # only "mpg" matches this

# Easy-to-type alias "namez"
namez(mtcars, "mpg")

# Use a regular expression to match a pattern
namez(mtcars, "r[ab]") # "drat", "carb"
namez(mtcars, "^d") # vars beginning with 'd' = "disp", drat

# Use this function to replace text in names!
umx_names(mtcars, "mpg", replacement = "hello") # "mpg" replaced with "hello"


# ========================================================================
# = Using the custom collapse option to quote each item, and wrap in c() =
# ========================================================================
namez(mtcars, "m", collapse = "vector") # Paste-able R-code for a vector

# Other options passed to R's grep command
umx_names(mtcars, "mpg" , invert = TRUE)  # Non-matches (instead of matches)
umx_names(mtcars, "disp", value  = FALSE) # Return indices of matches 
umx_names(mtcars, "disp", value  = "grepl")  # which var matches disp
umx_names(mtcars, "^d"  , fixed  = TRUE)  # Vars containing literal '^d' (none...)

# =======================================
# = Examples using built-in GFF dataset =
# =======================================

# Just show phenotypes for Twin 1
umx_names(GFF, "_T1$") # twin 1
# "zyg" "sex1" "age_T1" "gff_T1" "fc_T1" "qol_T1" "hap_T1"...

umx_names(GFF, "2$") # names ending in 2
umx_names(GFF, "[^12bs]$") # doesn't end in `1`, `2`, `b`, or `s`
# "zyg_6grp" "zyg_2grp" "divorce"
umx_names(mxData(twinData[, c("wt1", "wt2")], type= "raw"))
umx_names(mxData(cov(twinData[, c("wt1", "wt2")], use="comp"), type= "cov", numObs= 1000))
umx_names(mxDataWLS(na.omit(twinData[, c("wt1", "wt2")]), type= "WLS"))

namez(umxMatrix("bob", "Full", 3,3)$labels)