Package 'ACEsimFit' reference manual

Title:	ACE Kin Pair Data Simulations and Model Fitting
Description:	A few functions aim to provide a statistic tool for three purposes. First, simulate kin pairs data based on the assumption that every trait is affected by genetic effects (A), common environmental effects (C) and unique environmental effects (E).Second, use kin pairs data to fit an ACE model and get model fit output.Third, calculate power of A estimate given a specific condition. For the mechanisms of power calculation, we suggest to check Visscher(2004)<doi:10.1375/twin.7.5.505>.
Authors:	Xuanyu Lyu [aut, cre], S.Mason Garrison [aut]
Maintainer:	Xuanyu Lyu <[email protected]>
License:	MIT + file LICENSE
Version:	0.0.0.9
Built:	2025-02-14 04:12:22 UTC
Source:	https://github.com/cran/ACEsimFit

fit_uniACE

Description

Use OpenMx to quickly fit a univariate ACE model

Usage

fit_uniACE(
  data_1,
  data_2,
  GroupRel = c(1, 0.5),
  GroupR_c = c(1, 1),
  lbound = FALSE
)
fit_uniACE(
  data_1,
  data_2,
  GroupRel = c(1, 0.5),
  GroupR_c = c(1, 1),
  lbound = FALSE
)

Arguments

`data_1`	A n by 2 `data.frame` consisting of the group1 kin pairs
`data_2`	A n by 2 `data.frame` consisting of the group2 kin pairs
`GroupRel`	A numeric vector specifying two genetic relatedness values of two groups of kin pairs
`GroupR_c`	A numeric vector specifying two common environment correlation coefficients of two groups of kin pairs
`lbound`	A logical value indicating if a lower boundary of .0001 will be imposed to the estimated A, C and E components

Value

Returns a list with the following:

`df_nested`	A `data.frame` displaying the nested comparison model between ACE, AE, CE, E models
`fitACE`	A `list` of all model fit information generated from OpenMx

The function to generate two groups of univariate kin pair(e.g., both MZ and DZ twins) data using a multivariate norm approach, given the ACE components.

Two approaches can be selected: a) simulate two groups of kin pairs using the genetic relatedness directly b) simulate two groups of kin pairs by combining MZ twins and DZ twins to achieve the required genetic relatedness (.5<R<1).

Usage

kinsim_double(
  GroupNames = c("KinPair1", "KinPair2"),
  GroupSizes = c(100, 100),
  GroupRel = c(1, 0.5),
  GroupR_c = c(1, 1),
  mu = c(0, 0),
  ace1 = c(1, 1, 1),
  ace2 = c(1, 1, 1),
  ifComb = FALSE
)
kinsim_double(
  GroupNames = c("KinPair1", "KinPair2"),
  GroupSizes = c(100, 100),
  GroupRel = c(1, 0.5),
  GroupR_c = c(1, 1),
  mu = c(0, 0),
  ace1 = c(1, 1, 1),
  ace2 = c(1, 1, 1),
  ifComb = FALSE
)

Arguments

`GroupNames`	A character vector specifying two names of the simulated kin pairs
`GroupSizes`	A numeric vector specifying two group sizes indicating the amount of kin pairs in respective group.
`GroupRel`	A numeric vector specifying two genetic relatedness values of the simulated kin pairs
`GroupR_c`	A numeric vector specifying two common environment correlation coefficients of the simulated kin pairs
`mu`	A numeric vector specifying two mean values for the generated variable of the kin pairs
`ace1`	A numeric vector specifying three variance components under an ACE (additive genetics, common environment, unique environment) structure for group1
`ace2`	A numeric vector specifying three variance components under an ACE (additive genetics, common environment, unique environment) structure for group2
`ifComb`	A logical value specifying the approach to achieve the required genetic relatedness value. `TRUE` = using combination approach. `FALSE` = using direct approach. (See function description for a detailed explanation of two approaches.)

Value

Returns data.frame with the following:

`GroupName`	group name of the kin pairs
`R`	level of relatedness for the kin pair
`r_c`	level of common envrionment correlation of the kin pairs
`id`	id
`A1`	Additive genetic component for kin1 of the kin pairs
`A2`	Additive genetic component for kin2 of the kin pairs
`C1`	shared-environmental component for kin1 of the kin pairs
`C2`	shared-environmental component for kin2 of the kin pairs
`E1`	non-shared-environmental component for kin1 of the kin pairs
`E2`	non-shared-environmental component for kin2 of the kin pairs
`y1`	generated variable i for kin1
`y2`	generated variable i for kin2

kinsim_single

Description

The function to generate one group of univariate kin pair (e.g., only DZ twins) data using a multivariate norm approach, given the ACE components.

Usage

kinsim_single(
  name = "KinPair1",
  Rel = 1,
  r_c = 1,
  n = 100,
  mu = 0,
  ace = c(1, 1, 1)
)
kinsim_single(
  name = "KinPair1",
  Rel = 1,
  r_c = 1,
  n = 100,
  mu = 0,
  ace = c(1, 1, 1)
)

Arguments

`name`	Assigned name for the simulated group of kin pairs
`Rel`	Genetic relatedness of the simulated kin pairs
`r_c`	Assumed common enviroment correlation
`n`	The number of generated kin pairs.(n PAIRS of data; The total number of participants is 2n)
`mu`	The mean for generated variable
`ace`	Vector of variance components under an ACE (additive genetics, common environment, unique environment) structure

Value

Returns data.frame with the following:

`GroupName`	group name of the kin pairs
`R`	level of genetic relatedness for the kin pairs
`r_c`	level of common envrionment correlation of the kin pairs
`id`	id
`A1`	Additive genetic component for kin1 of the kin pairs
`A2`	Additive genetic component for kin2 of the kin pairs
`C1`	shared-environmental component for kin1 of the kin pairs
`C2`	shared-environmental component for kin2 of the kin pairs
`E1`	non-shared-environmental component for kin1 of the kin pairs
`E2`	non-shared-environmental component for kin2 of the kin pairs
`y1`	generated variable i for kin1
`y2`	generated variable i for kin2

Power_LS

Description

The function is designed for calculating the power of heritability estimation from ACE models given the parameter settings. Or calculate one of the parameter settings (N,R,h2,c2) given the rest of known parameters. This power calculator is made based on the Least Squares theory and follows the mathematical derivation proposed by Visscher(2004).

Usage

Power_LS(N1, N2, power, p_N1 = NULL, h2, c2, R1 = 1, R2 = 0.5, alpha = 0.05)
Power_LS(N1, N2, power, p_N1 = NULL, h2, c2, R1 = 1, R2 = 0.5, alpha = 0.05)

Arguments

`N1`	The number of kin pairs for group1 (amount of PAIRS)
`N2`	The number of kin pairs for group2
`power`	The power of heritability estimation. Specified if you want to return the required sample sizes.
`p_N1`	The proportion of kin group1 over the . Required to be specified if the user wants to calculate the N1 and N2 simultaneously.
`h2`	The assumed standard heritability value of the target trait. 0 < h2 < 1
`c2`	The assumed standard common environmental effects on the target trait. 0 < c2 < 2
`R1`	The genetic relatedness of kin pair group1
`R2`	The genetic relatedness of kin pair group2
`alpha`	The type-one error rate for heritability estimation.

Value

A numeric vector of power when N1 and N2 are both specified.
A numeric vector of N1 (or N2) when N2 (or N1) is specified. A numeric vector of N1 and N2 when RatioN is specified.

Sim_Fit

Description

A function to simulate a set of kin pair data and fit them with ACE models. Can be helpful with checking model performance for a given parameter setting.

Usage

Sim_Fit(
  GroupNames = c("KinPair1", "KinPair2"),
  GroupSizes = c(100, 100),
  nIter = 100,
  SSeed = 62,
  GroupRel = c(1, 0.5),
  GroupR_c = c(1, 1),
  mu = c(0, 0),
  ace1 = c(1, 1, 1),
  ace2 = c(1, 1, 1),
  ifComb = FALSE,
  lbound = FALSE,
  saveRaw = FALSE
)
Sim_Fit(
  GroupNames = c("KinPair1", "KinPair2"),
  GroupSizes = c(100, 100),
  nIter = 100,
  SSeed = 62,
  GroupRel = c(1, 0.5),
  GroupR_c = c(1, 1),
  mu = c(0, 0),
  ace1 = c(1, 1, 1),
  ace2 = c(1, 1, 1),
  ifComb = FALSE,
  lbound = FALSE,
  saveRaw = FALSE
)

Arguments

`GroupNames`	A character vector specifying two names of the simulated kin pairs
`GroupSizes`	A numeric vector specifying two group sizes indicating the amount of kin pairs in respective group.
`nIter`	A numeric value specifying the number of iteration you want to run given the parameters assigned (i.e. the number of model fitting results you want to get)
`SSeed`	An integer specifying the starting seed of the random number. This parameter will make sure the simulated results are replicable across time
`GroupRel`	A numeric vector specifying two genetic relatedness values of the simulated kin pairs
`GroupR_c`	A numeric vector specifying two common environment correlation coefficients of the simulated kin pairs
`mu`	A numeric vector specifying two mean values for the generated variable of the kin pairs
`ace1`	A numeric vector specifying three variance components under an ACE (additive genetics, common environment, unique environment) structure for group1
`ace2`	A numeric vector specifying three variance components under an ACE (additive genetics, common environment, unique environment) structure for group2
`ifComb`	A logical value specifying the approach to achieve the required genetic relatedness value. `TRUE` = using combination approach. `FALSE` = using direct approach. (See function description for a detailed explanation of two approaches.)
`lbound`	A logical value indicating if a lower boundary of .0001 will be imposed to the estimated A, C and E components
`saveRaw`	A logical value specifying if the raw simulated data should be saved in the output list

Value

Returns a two-level list. Level-one is the number of iterations. Level-two is the model fitting results and raw data (if saveRaw = TRUE) of the simulated data from the respective iteration. Level-two includes:

`Results`	A `list` including 1) A `data.frame` displaying the nested comparison model between ACE, AE, CE, E models and 2) A `list` of all model fit information generated from OpenMx
`Data`	A `data.frame` consists of the simulated raw data

Package 'ACEsimFit'

Help Index

fit_uniACE

Description

Usage

Arguments

Value

kinsim_double

Description

Usage

Arguments

Value

kinsim_single

Description

Usage

Arguments

Value

Power_LS

Description

Usage

Arguments

Value

Sim_Fit

Description

Usage

Arguments

Value