solarius (version 0.3.0.2)

solarPolygenic: Run polygenic analysis.

Description

The polygenic analysis is conducted in the following sequence: export data to a directory by df2solar function, form a SOLAR call with a list of settings and options, execute SOLAR by solar function, parse output files and store results in an object of solarPolygenic class (see solarPolygenicClass).

Usage

solarPolygenic(formula, data, dir, kinship, traits, covlist = "1", covtest = FALSE, screen = FALSE, household = as.logical(NA), transforms = character(0), alpha = 0.05, polygenic.settings = "", polygenic.options = "", verbose = 0, ...)

Arguments

formula

an object of class formula or one that can be coerced to that class. It is a symbolic description of fixed effects (covariates) to be fitted. If the model does not have any covariates, then the formula looks like trait ~ 1, where 1 means the trait mean parameter.

data

A data frame containing the variables in the model, including ID fields needed to construct random effects: genetic and house-hold (both optional). Other classes such as list, environment or object coercible by as.data.frame to a data frame are not supported.

dir

an optional character string, the name of directory, where SOLAR performs the analysis. In this case, the analysis within related input/output files is conducted in the given folder instead of a temporary one (the default work flow).

kinship

A matrix of the kinship coefficients (custom kinship matrix). The IDs are required to be in row and column names. Currently, it does not work for unrelated individuals (SOLAR issue).

traits

a vector of characters to specify trait(s) in the model. It is alternative to the formula interface.

covlist

a vector of characters to specify fixed effects (covariates) in the model. It is alternative to the formula interface. It could be convenient to indicate covariates in the SOLAR format, for example, "age^1,2,3#sex" that means sex age agesex age^2 age^2sex age^3 age^3*sex. The default value is "1".

covtest

a logical value, indicating whether to test the significance of the fixed effects (covariates). Likelihood ratio test (LRT) is used by SOLAR. polygenic SOLAR command is called with a combination of -screen -all options. As a result, cf slot will have p-values in pval column. The default value is FALSE.

screen

a logical value, indicating whether to screen the fixed effects (covariates). polygenic SOLAR command is called with -screen option. As a result, only significant covariates will be maintained in the model. The default value is FALSE.

household

a logical value, saying to forcedly include or exclude the house-hold effect. The default value is as.logical(NA), that means the following behavior in SOLAR. If data has hhid or similar column, then the house-hold effect is added to the model and tested by SOLAR. Otherwise, there is no any variable indicating the house-hold effect neither in data nor in the model. If household is TRUE, then polygenic SOLAR command is called with -keephouse option. If household is FALSE, then house SOLAR command is not called previously to calling polygenic SOLAR command (modeling of the house-hold effect is omitted).

transforms

a named vector of characters, indicating the transformations to be applied to traits. A list of available transforms is returned by function availableTransforms. If the model is univariate, the name of transformation is not necessary and can be omitted. The default value is character(0).

alpha

a number between 0 an 1, that is the value of -prob option of polygenic SOLAR command. That is the probability level for keeping covariates as significant. The default value in SOLAR is 0.1, but the default value here is 0.05. This parameter makes the polygenic SOLAR call to be like polygenic -prob 0.05.

polygenic.settings

A vector of characters, that contains SOLAR commands to be executed just before calling polygenic. For example, the liability threshold model applied to a binary trait (the default behavior in SOLAR). This behavior is disabled by setting the given argument to "option EnableDiscrete 0". The default value is "".

polygenic.options

A character of options to be passed to polygenic SOLAR command. For example, the comprehensive analysis of a bivariate model might be parametrized by setting this parameter to "-testrhoe -testrhog -testrhoc -testrhop -rhopse". See SOLAR help page for polygenic command for more details (http://solar.txbiomedgenetics.org/doc/91.appendix_1_text.html#polygenic). The default value is "".

verbose

An non-negative integer of the verbose level. The default value is 0.

...

additional parameters to be passed to other functions called inside of solarPolygenic. For example, it might be a parameter log.base for transformTrait function in the case transform is equal to "log".

Value

An object of solarPolygenic class. See solarPolygenicClass.

Examples

### load data and check out ID names
data(dat30)
matchIdNames(names(dat30))

## Not run: 
# ### basic (univariate) polygenic model
# mod <- solarPolygenic(trait1 ~ age + sex, dat30)
# 
# ### (univariate) polygenic model with parameters
# mod <- solarPolygenic(trait1 ~ age + sex, dat30, covtest = TRUE)
# mod$cf # look at test statistics for covariates
# 
# ### basic (bivariate) polygenic model
# mod <- solarPolygenic(trait1 + trait2 ~ 1, dat30)
# mod$vcf # look at variance components
# 
# ### (bivariate) polygenic model with trait specific covariates
# mod <- solarPolygenic(trait1 + trait2 ~ age + sex(trait1), dat30)
# 
# ### (bivariate) polygenic model with a test of the genetic correlation
# mod <- solarPolygenic(trait1 + trait2 ~ 1, dat30, polygenic.options = "-testrhog")
# mod$lf # look at a p-value of the test
# 
# ### transforms for (univariate) polygenic model
# mod <- mod <- solarPolygenic(trait1 ~ 1, dat30, transforms = "log")
# 
# ### transforms for (bivariate) polygenic model
# mod <- solarPolygenic(trait1 + trait2 ~ 1, dat30,
#    transforms = c(trait1 = "log", trait2 = "inormal"))
# 
# ### SOLAR format of introducing covariates
# mod <- solarPolygenic(traits = "trait1", covlist = "age^1,2,3#sex", data =  dat30)
# mod$cf # 8 covariate terms will be printed
# 
# ## End(Not run)