\name{AssociateWithGenes}
\alias{AssociateWithGenes}
\title{ Associates a vector of probe positions with the nearest input transcription start site. }
\description{
Associates a vector of probes, with known genomic positions, to the nearest transcription start site (TSS).

If argument D is specified, returns ALL genes with a TSS < D bp from pID.  Otherwise, the nearest gene is returned for each probe.

Returns vector composed of the following columns: 
  ProbeID    -- Unique probe ID.
  GeneID     -- Gene/ transcript ID.
  pgDistance -- Distance between ProbeID and GeneID TSS; 
                Positive values indicate upstream of the TSS.
                Negative values indicate downstream.
}
\usage{
AssociateWithGenes(kgID, kgCHR, kgSTR, kgSTART, kgEND, pID, pCHR, pMID, D=NULL)
}
\arguments{
  \item{kgID}{ Vector of gene IDs, one for each transcription start site. }
  \item{kgCHR}{ Vector of gene chromosomes, in the format "chr1", "chr2", ..., "chrX", "chrY". }
  \item{kgSTR}{ Vector of strand: "+" for a gene on the "+1" strand, "-" for the "-1" strand. }
  \item{kgSTART}{ Vector of start positions for each the transcript relative to the chromosome, NOT the start of transcription. }
  \item{kgEND}{  Vector of end positions for each the transcript relative to the chromosome.  }
  \item{pID}{  Vector of UniqueIDs for each probe being evaluated.  }
  \item{pCHR}{  Vector of chromosomes, in the format "chr1", "chr2", ..., "chrX", "chrY".  }
  \item{pMID}{  Vector of start positions, one for each of the probes being annotated.  }
  \item{D}{ Threshold distance: if specified, returns all genes with a TSS < D bp from pID.  Otherwise the nearest gene is returned for each probe. }
}
\author{ Charles Danko }
\examples{
data(KnownGenes)

## Calculate the gene nearest to each probe in Einter data frame.
NearestGenes <- AssociateWithGenes(KG[,1], KG[,2], KG[,3], KG[,4], KG[,5], 
    Einter[,1], Einter[,3], (as.integer(Einter[,2])+13))

## Returns all genes within 1 Kb of each probe in Einter.
## Probes that do not have a gene within 1 Kb are not returned.
NearestGenes <- AssociateWithGenes(KG[,1], KG[,2], KG[,3], KG[,4], KG[,5], 
    Einter[,1], Einter[,3], (as.integer(Einter[,2])+13), D=1000)
}
\keyword{ data }