sim_trait_model: Simulate a complex trait from a fixed trait model

In OchoaLab/simtrait: Simulate Complex Traits from Genotypes

Simulate a complex trait from a fixed trait model

Description

This function requires a trait model, which contains values for all of its variance components and intercept coeficient, as well as pre-determined causal loci indexes along with their coefficients, and simply simulates the traits with genetic effects and random non-genetic effects, for the individuals provided. This is useful to simulate traits for new individuals from a pre-existing model that was constructed using some previous data, so that the trait is fundamentally the same in all individuals (rather than a new random trait as sim_trait does for each call).

Usage

sim_trait_model(
  model,
  X,
  labs = NULL,
  loci_on_cols = FALSE,
  X_subset = FALSE,
  skip_checks = FALSE
)

Arguments

model	A list returned by a previous sim_trait call. This list must have scalar values with names sigma_sq, herit, sigma_sq_residual, alpha; if herit > 0, then causal_indexes and causal_coeffs vectors are also required in this list. Lastly, either labs and model$labs_sigma_sq must be both missing, or both must be present.
X	The m-by-n genotype matrix (if loci_on_cols = FALSE, transposed otherwise), or a BEDMatrix object. This is a numeric matrix consisting of reference allele counts (in c(0, 1, 2, NA) for a diploid organism).
labs	Optional labels assigning individuals to groups, to simulate environment group effects. Values can be numeric or strings, simply assigning the same values to individuals in the same group. If vector (single environment), length must be number of individuals. If matrix (multiple environments), individuals must be along rows, and environments along columns. The environments are not required to be nested. If this is non-NULL, then labs_sigma_sq must also be given!
loci_on_cols	If TRUE, X has loci on columns and individuals on rows; if FALSE (the default), loci are on rows and individuals on columns. If X is a BEDMatrix object, loci are always on the columns (loci_on_cols is ignored).
X_subset	If TRUE, X is treated as if it were already subset to the desired causal loci. Otherwise (default) X will be subset internally using model$causal_indexes.
skip_checks	If TRUE, skips validations of input model and other parameters. Not recommended for regular users; this is provided for sim_trait() internal use only, which calls sim_trait_model(), since these checks are redundant with sim_trait()'s own validations.

Value

The same type of named list returned by sim_trait(), please see that for more details. This includes the desired trait values, as well as copies of the input model parameters.

See Also

sim_trait() for simulating traits from scratch, picking random causal variants and their coefficients from various models.

Examples

# make two genotype matrices, one to construct the initial trait,
# the second one is a new dataset from which we want to simulate the same trait.
# They should have the same loci (number of rows), but individuals should be different!
X <- matrix(
    data = c(
        0, 1, 2,
        1, 2, 1,
        0, 0, 1
    ),
    nrow = 3,
    byrow = TRUE
)
X2 <- matrix(
    data = c(
        2, 1,
        2, 0,
        1, 1
    ),
    nrow = 3,
    byrow = TRUE
)

# here's a minimal `sim_trait` call that simulates a trait of interest from the first dataset
model <- sim_trait( X = X, m_causal = 2, herit = 0.7, kinship = 0.2 )

# use the same model to simulate traits for the new individuals!
obj <- sim_trait_model( model, X2 )
# trait vector for new individuals:
obj$trait

OchoaLab/simtrait documentation built on July 4, 2025, 3:48 a.m.