\HeaderA{PercentPos.FCS}{Calculate the Percent Positive given a percentile}{PercentPos.FCS}
\aliasA{percentile.FCS}{PercentPos.FCS}{percentile.FCS}
\keyword{dplot}{PercentPos.FCS}
\keyword{math}{PercentPos.FCS}
\begin{Description}\relax
From a sample of observations, the percentile for a given percent is
computed as the value in which there is a given percent of
observations that are lower than it.  Using
\code{\LinkA{percentile.FCS}{percentile.FCS}} will obtain the percentile of interest in
a given vector of values.

Given a sample of observed values, the percent positive over a certain
percentile value will be calculated and output by using
\code{\LinkA{PercentPos.FCS}{PercentPos.FCS}}.
\end{Description}
\begin{Usage}
\begin{verbatim}

percentile.FCS(x.vector, percent = 0.999)

PercentPos.FCS(st.data, percentile)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x.vector}] numerical vector of observations usually from the
control data
\item[\code{percent}] numeric; the percent at which to obtain the percentile
\item[\code{st.data}] numerical vector of observations; usually of the
cytokine response of the stimulated sample
\item[\code{percentile}] numerical value of the threshold; usually the 99.9th
percentile of the corresponding unstimulated/control sample
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Specifically \code{\LinkA{percentile.FCS}{percentile.FCS}} is used to obtain the
percentiles for \code{\LinkA{PercentPos.FCS}{PercentPos.FCS}}
and \code{\LinkA{ROC.FCS}{ROC.FCS}} in the analysis of the upper tail distributions
of the stimulated and controls samples of cytokine responses,
especially of the Interferon Gamma variable, among HIV positive and
HIV negative individuals.  This function and analysis can be applied
to different scenerios as well.

Usually the Interferon Gamma variable
from the FCS object (after gating and subsequent subsets (See
\code{\LinkA{createGate}{createGate}} and \code{\LinkA{extractGatedData}{extractGatedData}})), is of interest.
The percentile is obtained from the unstimulated or control sample
and 100* Percent positives among the cells/observations of the stimulated
sample is obtained based on the 99.9th percentile of the control
sample. There are differences in the tails of these distributions
(stimulated versus control) between HIV positive and
HIV negative samples that might better distinguish HIV positive and
HIV negative samples. This method was proposed by Zoe Moodie.
\end{Details}
\begin{Value}
For \code{\LinkA{percentile.FCS}{percentile.FCS}}:

the percentile is returned; the percentile is defined as the numeric value of the observation at the which
there is a given percent of observations below this value; the
value's label or name
is the position of the value in the input vector 'controldata'

For \code{\LinkA{PercentPos.FCS}{PercentPos.FCS}}:  

\begin{ldescription}
\item[\code{percent.pos}] the fraction of the observations above or equal to
the threshold/percentile
\item[\code{total.num}] total number of observations in the sample
\end{ldescription}
\end{Value}
\begin{Note}\relax
Please note that Percentage Positive = 100 * (percent positive).
\end{Note}
\begin{Author}\relax
A.J. Rossini and J.Y. Wan
\end{Author}
\begin{References}\relax
Zoe Moodie and Mario Roederer
\end{References}
\begin{SeeAlso}\relax
data 'PerPosROC' in \pkg{rfcdorig}
package, \code{\LinkA{ROC.FCS}{ROC.FCS}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

if (require(rfcdmin)){

data.there<-is.element(c("st.1829", "unst.1829", "unst.DRT", "st.DRT"),objects())
if ( ( sum(data.there) != length(data.there) )){
## obtaining the FCS objects from VRC data
data(VRCmin)
}
#hiv negative one individual, 1829
#stimulated sample
INFg.st.neg<-st.1829@data[,4]
#control sample
INFg.unst.neg<-unst.1829@data[,4]

#hiv positive one individual, DRT
#stimulated sample
INFg.st.pos<-st.DRT@data[,4]
#control sample
INFg.unst.pos<-unst.DRT@data[,4]

c.neg<-percentile.FCS(INFg.unst.neg)
c.pos<-percentile.FCS(INFg.unst.pos)

#percent positive for two individuals
p.neg<-PercentPos.FCS(INFg.st.neg, c.neg)
p.pos<-PercentPos.FCS(INFg.st.pos, c.pos)

### percentage positive
ptg.neg<-100*p.neg$percent.pos
ptg.pos<-100*p.pos$percent.pos
}

\end{ExampleCode}
\end{Examples}

