\name{KS.flowcytest}
\alias{KS.flowcytest}
\alias{KS}
\title{Kolmogorov Smirnoff Test 2-sample}
\description{
  Provides a Kolmogorov Smirnoff 2-sample Test to determine if the
  distribution of the control data is different from the
  distribution of the stimulated data (for which both datasets are of
  the same variable).  See also the function 'ks.test' in the \pkg{stats}.  A
  density plot made by the function 'bkde' in \pkg{KernSmooth}
  package is also
  shown.
}
\usage{
  KS.flowcytest(controldata, stimuldata,
                title="", varname = "", yupper = 0.01,
                xlimit = c(0, 1025), alternative="two.sided",
                KS.plotted=TRUE,
                MY.DEBUG=TRUE,...)
}
\arguments{
  \item{controldata}{a vector of numeric values of the control data}
  \item{stimuldata}{a vector of numeric values of the stimulated/case data}
  \item{title}{character string of the plot title}
  \item{varname}{character string of the name of the variable}
  \item{yupper}{the upper limit of the densities calculated}
  \item{xlimit}{a vector indicating the range of the controldata and the
    stimuldata}
  \item{alternative}{character string of the alternative hypothesis:

    1.  "two sided" : Two sided alternative hypothesis

    2. "less": One sided alternative hypothesis: controldata
      distribution is less than the stimuldata distribution

    3.  "greater" One sided alternative hypothesis: controldata
    distribution is greater than the stimuldata distribution
    
  }
  \item{KS.plotted}{boolean to display the corresponding plot; default
    is TRUE and the plot will be displayed}
  \item{MY.DEBUG}{boolean; if TRUE, the test is printed out with
    comments; if FALSE then these comments are surpressed}
  \item{...}{parameters for the stimuldata distribution specified in
    \code{\link{ks.test}}}
}

\details{
 In general, the control and the stimulated data come from the
 Interferon Gamma Data Variable of a FCS R object.
}

\value{
  \item{pval.2sid.KS}{p value of the two sided Kolmogorov Smirnoff test}
  \item{Alt.Hypoth.KS}{The Alternative Hypthesis as a string}
  \item{method.KS}{the method used}
  \item{dataname.KS}{the name of the data}
  A superimposed plot of the densities of the control and the stimulated
  dataset is also displayed.
  
}
\references{ See \code{\link{ks.test}}}
\author{A.J. Rossini and J.Y. Wan}
\note{Other flowcytests are available such as \code{pkci2.flowcytest},
  \code{ProbBin.flowcytest}, \code{KS.flowcytest}, which test the
  equivalence of two sample distributions. Generally, comparing the control and
  stimulated samples of the interferon gamma variable is of interest.}
\section{WARNING}{Usually the FCS object is gated and subset prior to
  this testing and analysis.}
\seealso{
  \code{\link{pkci2.flowcytest}},
  \code{\link{ProbBin.flowcytest}},
  \code{\link{runflowcytests}},
  \code{\link{ks.test}},
  \code{\link[KernSmooth]{bkde}}
}
\examples{
 
    ## different distributions
    control<-rnorm(1000, mean=3, sd=.7)
    stimulated<-rnorm(1000, mean=2, sd=.5)

    if (interactive()==TRUE) {
      output.same <- KS.flowcytest(control, stimulated,
                                   title="Different Distributions",
                                   varname="Interferon Gamma",
                                   yupper=1, xlimit=c(-5,8))
    }
    ## same distribution
    stimulated2<-rnorm(1000, mean=3, sd=.7)
    if (interactive()==TRUE) {
      output.diff <- KS.flowcytest(control, stimulated2,
                                   title="Same Distributions",
                                   varname="Interferon Gamma",
                                   yupper=1, xlimit=c(-5,8))
    }

    ## obtaining the FCS objects from VRC data
    if (require(rfcdmin)) {
      data.there<-is.element(c("st.1829", "unst.1829", "st.DRT", "unst.DRT"),objects())
      if ((sum(data.there) != length(data.there))) {
        ## obtaining the FCS objects from VRC data
        data(VRCmin)
      }

      ## This only serves as an example.  Usually the FCS object is
      ## gated and then subset

      ## HIV negative individual 1829
      ## only the first 2000 cells are selected

      IFN.control<-unst.1829@data[1:2000,4]
      IFN.stimul<-st.1829@data[1:2000,4]
     
      if (interactive()==TRUE){
        KS.flowcytest(IFN.control, IFN.stimul,
          title="HIV Negative Individual 1829", varname="Interferon Gamma",
          yupper=.006)
      }
      ## HIV positive individual DRT
      ## only the first 2000 cells are selected

      IFN.control2<-unst.DRT@data[1:2000,4]
      IFN.stimul2<-st.DRT@data[1:2000,4]
      
      if (interactive()){

      KS.flowcytest(IFN.control2, IFN.stimul2,
            title="HIV Positive Individual DRT", varname="Interferon Gamma",
            yupper=.006)
    }
    ## This is an artifical example, but one would expect the
    ## distributions of the stimulated and control samples
    ## to be the same in the HIV negative individual 1829
    ## and to be different in the HIV positive individual DRT
    ## The test in this example is a bit contrived but
    ## the bigger picture is achieved.
  }
  
}
\keyword{dplot}% at least one, from doc/KEYWORDS
\keyword{distribution}