\name{gwasExactHW}
\alias{gwasExactHW}
\title{Hardy-Weinberg Equilibrium testing}

\description{
This function performs exact Hardy-Weinberg Equilibrium testing (using Fisher's Test) over a selection of SNPs.  
It also performs genotype counts, calculates allele frequencies, and calculates inbreeding coefficients.
}

\usage{
gwasExactHW(genoData, 		
	    scan.chromosome.filter = NULL,
	    scan.exclude = NULL,
	    geno.counts = TRUE,
	    chromosome.set = NULL,
	    block.size = 5000, 
	    verbose = TRUE,
	    outfile = NULL)
}

\arguments{
  \item{genoData}{\code{\link{GenotypeData}} object, should contain sex and
    phenotypes in scan annotation}
  
  \item{scan.chromosome.filter}{a logical matrix that can be used to
  exclude some chromosomes, some scans, or some specific scan-chromosome
  pairs. Entries should be \code{TRUE} if that scan-chromosome pair should be
  included in the analysis, \code{FALSE} if not. The number of rows must be
  equal to the number of scans in \code{genoData}, and the number of
  columns must be equal to the largest integer chromosome value in \code{genoData}. The column number must match the chromosome number.
e.g. A scan.chromosome.filter matrix used for an analyis when
  \code{genoData} has SNPs with chromosome=(1-24, 26, 27) (i.e. no Y
  (25) chromosome SNPs) must have 27 columns (all \code{FALSE} in the
  25th column). But a scan.chromosome.filter matrix used for an analysis
  \code{genoData} has SNPs chromosome=(1-26) (i.e no Unmapped (27)
  chromosome SNPs) must have only 26 columns.}

  \item{scan.exclude}{an integer vector containing the IDs of entire scans to
    be excluded.}
    
\item{geno.counts}{if \code{TRUE} (default), genotype counts are
  returned in the output data.frame.}

  \item{chromosome.set}{integer vector with chromosome(s) to be
  analyzed.  Use 23, 24, 25, 26, 27 for X, XY, Y, M, Unmapped
  respectively.}

  \item{block.size}{Number of SNPs to be read from \code{genoData} at
    once.}
  
\item{verbose}{if \code{TRUE} (default), will print status updates while the function runs. 
e.g. it will print "chr 1 block 1 of 10" etc. in the R console after each block of SNPs is done being analyzed.}

\item{outfile}{a character string to append in front of ".chr.i_k.RData" for naming the output data-frame; 
where i is the first chromosome, and k is the last chromosome used in
that call to the function.  "chr.i_k." will be
    omitted if \code{chromosome.set=NULL}.}
}

\details{
HWE calculations are performed with the \code{\link{HWExact}}
function in the \code{\link{GWASExactHW}} package.
  
For the X chromosome, only female samples will be used in all calculations (since males are excluded from HWE testing on this chromosome). 
Hence if chromosome.set includes 23, the scan annotation of genoData should provide the sex of the sample ("M" or "F") i.e. there should be a column named "sex" with "F" for females and "M" for males.

Y, M, and U (25, 26, and 27) chromsome SNPs are not used in HWE
analysis, so all returned values for these SNPs will be \code{NA}.
}

\value{
  If \code{outfile=NULL} (default), all results are returned as a single
  data.frame.  If \code{outfile} is specified, no data is returned but
  the function saves a data-frame with the naming convention as
  described by the argument \code{outfile}.
  
  The first three columns of the data-frame are:
\item{snpID}{snpID (from the snp annotation) of the SNP}
\item{chromosome}{chromosome (from the snp annotation) of the SNP. The integers 23, 24, 25, 26, 27 are used for X, XY, Y, M, Unmapped respectively.  }
\item{position}{position (from the snp annotation) of the SNP}

If \code{geno.counts = TRUE}:
\item{nAA}{number of AA genotypes in samples}
\item{nAB}{number of AB genotypes in samples}
\item{nBB}{number of BB genotypes in samples} 

\item{MAF}{minor allele frequency.}
\item{minor.allele}{the minor allele. Takes values "A" or "B".}
\item{f}{the inbreeding coefficient.}

\item{p.value}{exact Hardy-Weinberg Equilibrium (using Fisher's Test)
  p-value.  \code{p.value} will be \code{NA} for monomorphic SNPs
  (\code{MAF == 0}).}


Warnings:

If \code{outfile} is not \code{NULL}, another file will be saved with the name
"outfile.chr.i_k.warnings.RData" that contains any warnings generated by
the function.
}

\author{Ian Painter, Matthew P. Conomos}

\seealso{\code{\link{HWExact}}}

\examples{
# The following example would perform exact Hardy-Weinberg equilibrium testing on all chromosomes in this data set.  It would also return genotype counts, minor allele frequencies, and inbreeding coefficients.

library(GWASdata)
data(affyScanADF)

# run only on YRI subjects
scan.exclude <- affyScanADF$scanID[affyScanADF$race != "YRI"]

# create data object
ncfile <- system.file("extdata", "affy_geno.nc", package="GWASdata")
nc <- NcdfGenotypeReader(ncfile)
genoData <-  GenotypeData(nc, scanAnnot=affyScanADF)

hwe <- gwasExactHW(genoData, scan.exclude=scan.exclude)

close(genoData)
}

\keyword{manip}