\name{pkci2.flowcytest}
\alias{pkci2.flowcytest}
\alias{pkci2}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Testing the difference of upper-tail distributions of two samples}
\description{
 This function calculates a cut-off value designating the lower bound
 of the upper tail as k.hat.pkci2, the given percentile of the control sample, and a 
 95\% confidence interval to test for a significant difference in proportion of stimulated cells and
 control cells above the threshold, k.hat.pkci2.
}
\usage{
pkci2.flowcytest(controldata, stimuldata, crit = 0.999, alpha = 0.05)
}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{controldata}{vector of data for control cells}
  \item{stimuldata}{vector of data for stimulated cells}
  \item{crit}{ the percent of control sample below the threshold, k.hat.pkci2}
  \item{alpha}{The Type I error rate for construction of (1-alpha)\% confidence interval }
}
\details{
  Sometimes the difference in two sample distributions (control and
  stimulated) lies in the upper tail (usually at k.hat.pkci2 threshold
  which is the 99.9th percentile of the control sample).  This function
  applies a standard normal test of the difference of two
  proportions (One proportion is obtained from the control sample, and
  one proportion is obtained from the stimulated sample.  Both
  proportions are defined as the proportion of cells within that
  particular sample that are above the k.hat.pkci2 threhold value.)
  Please note that the standard normal approximation is used because
  it is assumed that the control and the stimulated samples are large in
  size (over 100 observations).
  
  The null hypothesis of the test is that the proportion of the control sample
  above the k.hat.pkci2 threshold is the same as the proportion of the
  stimulated sample above the k.hat.pkci2 (ie, the distribution of cells
  in the tails of both the control and the stimulated samples are the
  same.)

  Two alternative hypotheses are investigated.  The one-sided
  alternative hypothesis states that the stimulated proportion is
  greater than the control proportion.  The two-sided alternative
  hypothesis is that the stimulated proportion is not equal to the
  control proportion.

  The respective p-values and a 95\% confidence interval is obtained
  from the Z statistic (standard normal statistic).
}
\value{
  \item{k.hat.pkci2}{the threshold which is the 100*crit-th percentile of the
    control sample, where crit is the user input value}
  \item{pc.hat.pkci2}{the proportion of control cells/data above the
    k.hat.pkci2 threshold}
  \item{ps.hat.pkci2}{the proportion of stimulated cells/data above the
    k.hat.pkci2 threshold}
   \item{lb.pkci2}{The numeric lower bound of the 95\% confidence
     interval from the Z statistic of the test}
   \item{up.pkci2}{The numeric upper bound of the 95\% confidence
     interval from the Z statistic of the test}
   \item{test.1pkci2}{0,1 indicator for the one-sided test: 1= reject the
     null hypothesis, 0=cannot reject the null hypothesis}
   \item{pval1.pkci2}{p-value of the one-sided test; Pr(Z > z.statistic)}
   \item{test.2pkci2}{0,1 indicator for the two-sided test: 1= reject the
     null hypothesis, 0=cannot reject the null hypothesis}
   \item{pval2.pkci2}{p-value of the two-sided test; Pr(|Z| > z.statistic )= Pr(Z > z.statistic) + Pr(Z <-z.statistic)}
}
\references{Zoe Moodie, PhD
 Statistical Center for HIV/AIDS Research and Prevention (SCHARP) 
 Fred Hutchison Cancer Research Center
 Seattle, WA 98109-1024                     
}
\author{Zoe Moodie and A.J. Rossini and J.Y. Wan}
\note{Other flowcytests are available such as \code{WLR.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{WLR.flowcytest}},
  \code{\link{ProbBin.flowcytest}}, \code{\link{KS.flowcytest}},
  \code{\link{runflowcytests}}, \code{\link{qnorm}},
  \code{\link{pnorm}} }

\examples{
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
  IFN.control<-unst.1829@data[1:2000,4]
  IFN.stimul<-st.1829@data[1:2000,4]

  output1.pkci2<-pkci2.flowcytest(IFN.control, IFN.stimul, crit=.9999)

## HIV positive individual DRT
  IFN.control2<-unst.DRT@data[1:2000,4]
  IFN.stimul2<-st.DRT@data[1:2000,4]
  output2.pkci2<-pkci2.flowcytest(IFN.control2, IFN.stimul2, crit=.9999)

## 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{univar}
\keyword{htest}