% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scan1coef.R
\name{scan1coef}
\alias{scan1coef}
\title{Calculate QTL effects in scan along one chromosome}
\usage{
scan1coef(
  genoprobs,
  pheno,
  kinship = NULL,
  addcovar = NULL,
  nullcovar = NULL,
  intcovar = NULL,
  weights = NULL,
  contrasts = NULL,
  model = c("normal", "binary"),
  zerosum = TRUE,
  se = FALSE,
  hsq = NULL,
  reml = TRUE,
  ...
)
}
\arguments{
\item{genoprobs}{Genotype probabilities as calculated by
\code{\link[=calc_genoprob]{calc_genoprob()}}.}

\item{pheno}{A numeric vector of phenotype values (just one phenotype, not a matrix of them)}

\item{kinship}{Optional kinship matrix, or a list of kinship matrices (one
per chromosome), in order to use the LOCO (leave one chromosome
out) method.}

\item{addcovar}{An optional numeric matrix of additive covariates.}

\item{nullcovar}{An optional numeric matrix of additional additive
covariates that are used under the null hypothesis (of no QTL) but
not under the alternative (with a QTL). This is needed for the X
chromosome, where we might need sex as a additive covariate under
the null hypothesis, but we wouldn't want to include it under the
alternative as it would be collinear with the QTL effects. Only
used if \code{kinship} is provided but \code{hsq} is not, to get
estimate of residual heritability.}

\item{intcovar}{An optional numeric matrix of interactive covariates.}

\item{weights}{An optional numeric vector of positive weights for the
individuals. As with the other inputs, it must have \code{names}
for individual identifiers.}

\item{contrasts}{An optional numeric matrix of genotype contrasts, size
genotypes x genotypes. For an intercross, you might use
\code{cbind(mu=c(1,1,1), a=c(-1, 0, 1), d=c(0, 1, 0))} to get
mean, additive effect, and dominance effect. The default is the
identity matrix.}

\item{model}{Indicates whether to use a normal model (least
squares) or binary model (logistic regression) for the phenotype.
If \code{model="binary"}, the phenotypes must have values in \eqn{[0, 1]}.}

\item{zerosum}{If TRUE, force the genotype or allele coefficients
sum to 0 by subtracting their mean and add another column with
the mean. Ignored if \code{contrasts} is provided.
\strong{Note}: the standard errors aren't quite right when \code{zerosum=TRUE};
use \code{\link[=fit1]{fit1()}} to get proper standard errors.}

\item{se}{If TRUE, also calculate the standard errors.}

\item{hsq}{(Optional) residual heritability; used only if
\code{kinship} provided.}

\item{reml}{If \code{kinship} provided: if \code{reml=TRUE}, use
REML; otherwise maximum likelihood.}

\item{...}{Additional control parameters; see Details;}
}
\value{
An object of class \code{"scan1coef"}: a matrix of estimated regression coefficients, of dimension
positions x number of effects. The number of effects is
\code{n_genotypes + n_addcovar + (n_genotypes-1)*n_intcovar}.
May also contain the following attributes:
\itemize{
\item \code{SE} - Present if \code{se=TRUE}: a matrix of estimated
standard errors, of same dimension as \code{coef}.
\item \code{sample_size} - Vector of sample sizes used for each
phenotype
}
}
\description{
Calculate QTL effects in scan along one chromosome with a
single-QTL model using Haley-Knott regression or a linear mixed
model (the latter to account for a residual polygenic effect), with
possible allowance for covariates.
}
\details{
For each of the inputs, the row names are used as
individual identifiers, to align individuals.

If \code{kinship} is absent, Haley-Knott regression is performed.
If \code{kinship} is provided, a linear mixed model is used, with a
polygenic effect estimated under the null hypothesis of no (major)
QTL, and then taken as fixed as known in the genome scan.

If \code{contrasts} is provided, the genotype probability matrix,
\eqn{P}, is post-multiplied by the contrasts matrix, \eqn{A}, prior
to fitting the model. So we use \eqn{P \cdot A}{P A} as the \eqn{X}
matrix in the model. One might view the rows of
\ifelse{html}{\out{<em>A</em><sup>-1</sup>}}{\eqn{A^{-1}}}
as the set of contrasts, as the estimated effects are the estimated
genotype effects pre-multiplied by
\ifelse{html}{\out{<em>A</em><sup>-1</sup>}}{\eqn{A^{-1}}}.

The \code{...} argument can contain several additional control
parameters; suspended for simplicity (or confusion, depending on
your point of view). \code{tol} is used as a tolerance value for linear
regression by QR decomposition (in determining whether columns are
linearly dependent on others and should be omitted); default
\code{1e-12}. \code{maxit} is the maximum number of iterations for
converence of the iterative algorithm used when \code{model=binary}.
\code{bintol} is used as a tolerance for converence for the iterative
algorithm used when \code{model=binary}. \code{eta_max} is the maximum value
for the "linear predictor" in the case \code{model="binary"} (a bit of a
technicality to avoid fitted values exactly at 0 or 1).
}
\examples{
# read data
iron <- read_cross2(system.file("extdata", "iron.zip", package="qtl2"))
\dontshow{iron <- iron[,c(7,19)] # reduce to chr 7 and 19}

# insert pseudomarkers into map
map <- insert_pseudomarkers(iron$gmap, step=1)

# calculate genotype probabilities
probs <- calc_genoprob(iron, map, error_prob=0.002)
\dontshow{probs[["7"]] <- probs[["7"]][,,1:5] # reduce to very small number}

# grab phenotypes and covariates; ensure that covariates have names attribute
pheno <- iron$pheno[,1]
covar <- match(iron$covar$sex, c("f", "m")) # make numeric
names(covar) <- rownames(iron$covar)

# calculate coefficients for chromosome 7
coef <- scan1coef(probs[,"7"], pheno, addcovar=covar)

# leave-one-chromosome-out kinship matrix for chr 7
kinship7 <- calc_kinship(probs, "loco")[["7"]]

# calculate coefficients for chromosome 7, adjusting for residual polygenic effect
coef_pg <- scan1coef(probs[,"7"], pheno, kinship7, addcovar=covar)

}
\references{
Haley CS, Knott SA (1992) A simple
regression method for mapping quantitative trait loci in line
crosses using flanking markers.  Heredity 69:315--324.

Kang HM, Zaitlen NA, Wade CM, Kirby A, Heckerman D, Daly MJ, Eskin
E (2008) Efficient control of population structure in model
organism association mapping. Genetics 178:1709--1723.
}
