RFGLS (version 1.0)

fgls: Feasible Generalized Least Squares regression with family GWAS data.

Description

Jointly estimates the fixed-effects coefficients and residual variance-covariance matrix in a generalized least squares model by maximizing the (multivariate-normal) likelihood function, via optim() in the Rbase distribution. The residual variance-covariance matrix is block-diagonal sparse, constructed with bdsmatrix() from the bdsmatrix package.

Usage

fgls(fixed, data = parent.frame(), tlist = tlist, sizelist = sizelist,
    sizeLab = "OOPP",Mz = TRUE,Bo = TRUE,Ad = TRUE,Mix = TRUE,indobs = TRUE,
    get.hessian=FALSE,vmat = NULL,subset, weights, na.action)

Arguments

fixed

An object of class 'formula' (or one that can be coerced to that class): a symbolic description of the model to be fitted. The RHS of the formula contains the fixed effects of the model.

data

An optional data frame, list or environment (or object coercible by as.data.frame() to a data frame) containing the variables in the model. If not found in data the variables are taken

tlist

The vector of the list of the family labels ("famlab") in the data. The length of the vector equals the number of family units. It should be ordered in the same order as the families appear in the data. Object tlist is created from the

sizelist

The vector of the list of the family sizes in the data. The length of the vector equals the number of family units. It should be ordered as the familin the same order as the families appear in the data. Object sizelist is created from

sizeLab

A character string indicating the maximum size of the families in the data. Must be one of the following strings:

• "OOPP", if the largest family has two offspring and both parents;
• "OPP", if the largest family ha

Mz

Logical (TRUE or FALSE). An indicator of whether Mz-twin families are in the data; must be set to FALSE if sizeLab="PP".

Bo

A logical indicator of whether bio-offspring (including DZ-twin) families are in the data; must be set to FALSE if sizeLab ="PP". Defaults to TRUE.

Ad

A logical indicator of whether adopted-offspring families are in the data; must be set to FALSE if sizeLab ="PP". Defaults to TRUE.

Mix

A logical indicator of whether "mixed" families, with 1 biological and 1 adopted offspring, are in the data; must be set to FALSE if sizeLab ="PP". Defaults to TRUE.

indobs

A logical indicator of whether there are "independent observations" who do not fit into a four-person nuclear family present in the data. If TRUE, a separate residual variance parameter will be estimated for those individuals.

get.hessian

Logical; default is FALSE. If TRUE, fgls() will include the Hessian matrix from optim() in its output list. Otherwise, the entry 'hessian' in the list will be NULL.

vmat

The previously estimated (or known) residual variance-covariance matrix (for conducting Rapid FGLS). If it is NULL (default), the matrix will be jointly estimated with the fixed-effects coefficients (FGLS). If not NULL

subset, weights, na.action

May be passed through fgls() as additional arguments to lm().

Value

• an object of class fgls. It includes the following components:
• coefficients
  The vector of regression coefficients for the fixed effects. They are ordered as their corresponding terms appear in the RHS of argument fixed.
• estimates
  The vector of MLEs of the parameters used to construct the residual variance-covariance matrix: correlations and variances.
• sigma
  The estimated residual covariance matrix. It is of class bdsmatrix. One of its slots, sigma@blocks, can be written to a single-column text file and subsequently read in by gls.batch(). (Due to its potential size, it is not advised to return sigma to R's standard output or print it to the console.)
• variance
  The estimated covariance matrix for the fixed-effects regression coefficients.
• ctable
  Table of coefficients reminiscent of output from summary.lm(). Each fixed-effect term (including the intercept) has one row of the table, which are ordered as the terms appear in argument fixed. Each row contains a point estimate, an estimated standard error, a t-statistic, and a two-tailed p-value.
• residuals
  Residuals from the feasible generalized-least-squares regression.
• fitted.values
  Predicted phenotype scores from the feasible generalized-least-squares regression.
• df.residual
  Residual degrees of freedom in the feasible generalized-least-squares regression.
• loglik
  The value of the loglikelihood function for the variance-covariance parameters, at its solution.
• iter
  Number of iterations, from the numerical optimization of variance-covariance parameters. Will be 0 if the residual variance-covariance matrix was provided as argument vmat.
• n
  Sample size (i.e., number of individual participants).
• call
  Echo of fgls() function call.
• hessian
  If get.hessian=TRUE, the Hessian matrix from optim() for the variance-covariance parameters; NULL otherwise.
• Function fgls() also prints to console the vector of variance and correlation parameter estimates it uses to construct the residual variance-covariance matrix.

Details

Function fgls() was primarily intended to be called automatically, from within gls.batch(), though it can be called directly if need be. The difficulty when directly invoking fgls() is supplying the function with arguments tlist and sizelist. However, these can be obtained easily via gls.batch.get().

References

Li X, Basu S, Miller MB, Iacono WG, McGue M: A Rapid Generalized Least Squares Model for a Genome-Wide Quantitative Trait Association Analysis in Families. Hum Hered 2011;71:67-82 (DOI: 10.1159/000324839)

See Also

gls.batch

Examples

data(pheno)
data(geno)
data(pedigree)
data(resVCmtx)
foo <- gls.batch.get(
  phenfile=pheno,
  genfile=data.frame(t(geno)),
  pedifile=pedigree, 
  outfile="example_output.txt", 
  covmtxfile.in=NULL,covmtxfile.out=paste(phen,"_cov_matrix.txt",sep=""),
  phen="Zscore", covars = "IsFemale",
  med = "rfgls", sizeLab = "OOPP", Mz = TRUE, Bo = TRUE, Ad = TRUE, Mix = TRUE,
  indobs = TRUE, col.names = TRUE, pediheader = FALSE,
  pedicolname=c("FAMID","ID","PID","MID","SEX"),
  sep.phe = "", sep.gen = "", sep.ped = "")

bar <- fgls(
  fixed=Zscore ~ snp.1 + IsFemale, data=foo$test.dat, sizelist=foo$sizelist, 
  tlist=foo$tlist, 
  sizeLab="OOPP",Mz = TRUE, Bo = TRUE, Ad = TRUE, Mix = TRUE, indobs = TRUE,
  get.hessian=FALSE,
  vmat = resVCmtx, #<--Resid. cov. matrix from fgls onto IsFemale only.
  subset=NULL, weights=NULL, na.action=NULL)
bar$ctable
##  To simultaneously estimate residual covariance matrix
##  and regression coefficients for snp.1 & IsFemale,
##  use the same syntax, except with vmat = NULL .