\HeaderA{pkci2.flowcytest}{Testing the difference of upper-tail distributions of two samples}{pkci2.flowcytest}
\aliasA{pkci2}{pkci2.flowcytest}{pkci2}
\keyword{univar}{pkci2.flowcytest}
\keyword{htest}{pkci2.flowcytest}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
pkci2.flowcytest(controldata, stimuldata, crit = 0.999, alpha = 0.05)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{controldata}] vector of data for control cells
\item[\code{stimuldata}] vector of data for stimulated cells
\item[\code{crit}] the percent of control sample below the threshold, k.hat.pkci2
\item[\code{alpha}] The Type I error rate for construction of (1-alpha)\% confidence interval 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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).
\end{Details}
\begin{Value}
\begin{ldescription}
\item[\code{k.hat.pkci2}] the threshold which is the 100*crit-th percentile of the
control sample, where crit is the user input value
\item[\code{pc.hat.pkci2}] the proportion of control cells/data above the
k.hat.pkci2 threshold
\item[\code{ps.hat.pkci2}] the proportion of stimulated cells/data above the
k.hat.pkci2 threshold
\item[\code{lb.pkci2}] The numeric lower bound of the 95\% confidence
interval from the Z statistic of the test
\item[\code{up.pkci2}] The numeric upper bound of the 95\% confidence
interval from the Z statistic of the test
\item[\code{test.1pkci2}] 0,1 indicator for the one-sided test: 1= reject the
null hypothesis, 0=cannot reject the null hypothesis
\item[\code{pval1.pkci2}] p-value of the one-sided test; Pr(Z > z.statistic)
\item[\code{test.2pkci2}] 0,1 indicator for the two-sided test: 1= reject the
null hypothesis, 0=cannot reject the null hypothesis
\item[\code{pval2.pkci2}] p-value of the two-sided test; Pr(|Z| > z.statistic )= Pr(Z > z.statistic) + Pr(Z <-z.statistic)
\end{ldescription}
\end{Value}
\begin{Section}{WARNING}
Usually the FCS object is gated and subset prior to
this testing and analysis.
\end{Section}
\begin{Note}\relax
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.
\end{Note}
\begin{Author}\relax
Zoe Moodie and A.J. Rossini and J.Y. Wan
\end{Author}
\begin{References}\relax
Zoe Moodie, PhD
Statistical Center for HIV/AIDS Research and Prevention (SCHARP) 
Fred Hutchison Cancer Research Center
Seattle, WA 98109-1024
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{WLR.flowcytest}{WLR.flowcytest}},
\code{\LinkA{ProbBin.flowcytest}{ProbBin.flowcytest}}, \code{\LinkA{KS.flowcytest}{KS.flowcytest}},
\code{\LinkA{runflowcytests}{runflowcytests}}, \code{\LinkA{qnorm}{qnorm}},
\code{\LinkA{pnorm}{pnorm}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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.
}

\end{ExampleCode}
\end{Examples}

