% $Id: LD.Rd 1069 2006-11-10 08:43:19Z warnes $
\name{LD}
\alias{LD}
\alias{LDband}
\alias{LDdist}
\alias{LDband.geneSet}
\alias{LDdist.geneSet}
\alias{summary.LD}

\title{Pairwise linkage disequilibrium between genetic markers.}
\description{
  Compute pairwise linkage disequilibrium between genetic markers
}
\usage{
LD(object, pooling.threshold = 0.1, founderOnly = FALSE, quiet = TRUE )
LDband(object, width=31,pooling.threshold=0.1, founderOnly=FALSE, quiet=TRUE)
LDband.geneSet(object,width=31,pooling.threshold=0.1, founderOnly=FALSE, quiet=TRUE)
LDdist.geneSet(object,posVec, maxDist, pooling.threshold=0.1, founderOnly=FALSE, quiet=TRUE)

summary.LD(object, 
           which = c("D", "D'", "r", "R^2", "X^2", "P-value", "LOD", "n"), 
           rowsep, 
           digits = 3, ...)
}
\arguments{
  \item{object}{ geneSet object }
  \item{width}{ window width }
  \item{posVec}{marker position}
  \item{maxDist}{size of the window based on distance}
  \item{pooling.threshold}{Threshold for LD calculation}
  \item{which}{ character string indicates which LD statistic should be print out }
  \item{rowsep}{ separator for rows }
  \item{digits}{ the desired number of digits after the decimal point  }
  \item{founderOnly}{Indicates if only founders are used to do the test.}
  \item{quiet}{Indicates if intermediate results should be output}
  \item{\dots}{additional optional arguments}
}
\details{
  Linkage disequilibrium (LD) is the non-random association of
  marker alleles and can arise from marker proximity or from selection
  bias.
  
  \code{LD} estimates the extent of LD for all pairs of
  genotypes contained in a \code{object}.  \code{LDband} computes the
  extent of LD of markers within a window containing
  \code{width} markers centered around each marker in \code{object}.

  The current (temporary) code only computes LD for markers with exactly
  2 variants.  For other markers, \code{NA} is returned. 

  Three estimators of LD are computed:
  \itemize{

    \item{D}{ raw difference in frequency between the
              observed number of AB pairs and the expected number:
      
      \deqn{%
 	D = p_{AB} - p_A p_B %
      }{%
 	D = p(AB) - p(A)*p(B) %
      }
      
    }
    \item{D'}{ scaled D spanning the range [-1,1] 
      
      
      \deqn{D' = \frac{D}{D_{max} } }{D' = D / Dmax}
      
      where, if D > 0:
      \deqn{%
  	D_{max} = \min( p_A p_b, p_a p_B )  %
      }{%
  	Dmax = min( p(A)p(b), p(a)p(B) )   %
      } 
      or if D < 0:
      \deqn{%
  	D_{max} = \max{ -p_A p_B, -p_a p_b }  %
      }{%
  	Dmax = max( -p(A)p(B), -p(a)p(b) )  %
      }
    }
    
    \item{r}{ correlation coefficient between the markers
      
      \deqn{%
 	r = \frac{-D}{\sqrt( p_A * p_a * p_B * p_b  )} %
      }{%
 	r = -D / sqrt( p(A) * p(a) * p(B) * p(b) ) %
      }
    }
  }
  
  where
  \itemize{
    \item{-}{ \eqn{p_A}{p(A)} is defined as the observed probability of
      allele 'A' for marker 1, }
    \item{-}{ \eqn{p_a=1-p_A}{p(a) = 1-p(A)} is defined as the observed probability of
      allele 'a' for marker 1, }
    \item{-}{\eqn{p_B}{p(B)} is defined as the observed probability of
      allele 'B' for marker 2, and }
    \item{-}{\eqn{p_b=1-p_B}{p(b) = 1- p(B)} is defined as the observed probability of
      allele 'b' for marker 2, and }
    \item{-}{\eqn{p_{AB}}{p(AB)} is defined as the probability of
      the marker allele pair 'AB'. }
  }

  For genotype data, AB/ab cannot be distinguished from
  aB/Ab. Consequently, we estimate \eqn{p_{AB}}{p(AB)} using maximum
  likelihood and use this value in the computations.
  }
\value{

  \code{LD} returns an object of class \code{LD}, while \code{LDband}
  and \code{LDdist} return objects of classes \code{LDband} and \code{LDdist}, 
  respectively.  All classes contain these
  slots:
  
  \item{call}{the matched call}
  \item{D}{Linkage disequilibrium estimate}
  \item{Dprime }{Scaled linkage disequilibrium estimate}
  \item{corr}{Correlation coefficient} 
  \item{nobs}{Number of observations}
  \item{chisq}{Chi-square statistic for linkage
      equilibrium (i.e., D=D'=corr=0)}
  \item{p.value}{Chi-square p-value for marker independence}
  \item{LOD}{LOD scores}

  For objects of class \code{LD}, the data slots are square matrixes
  one row and one column for each marker.  In the current
  implementation, only upper off-diagonal values are computed and
  stored.

  Objects of class \code{LD} contain matrixes with one row for each
  marker, and \code{width} columns, where each column is a different
  offset from the marker of interest.  In the current implementation,
  non-diagonal elements are computed.

  \code{summary.LD} returns a list with components:
  \item{tab}{Description of 'tab'}
  \item{statlist}{Description of 'statlist'}
  \item{which}{Description of 'which'}
  \item{object}{Description of 'object'}
}
\author{ Gregory R. Warnes \email{warnes@bst.rochester.edu} }
\seealso{ \code{\link{geneSet-class}}, \code{\link{diseq}}  }
\examples{

data(CAMP)

ld <- LD(CAMP)
print(ld)

ldb <- LDband(CAMP)
print(ldb)

ldd <- LDdist(CAMP, posVec=1:8, maxDist=3)
print(ldd)


}
\keyword{misc}