\name{PercentPos.FCS}
\alias{PercentPos.FCS}
\alias{percentile.FCS}

%- Also NEED an `\alias' for EACH other topic documented here.
\title{Calculate the Percent Positive given a percentile}
\description{
  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{\link{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{\link{PercentPos.FCS}}.
  
}
\usage{

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

PercentPos.FCS(st.data, percentile)
}
%- maybe also `usage' for other objects documented here.
\arguments{

  \item{x.vector}{numerical vector of observations usually from the
    control data}
  \item{percent}{numeric; the percent at which to obtain the percentile}
  
  \item{st.data}{numerical vector of observations; usually of the
    cytokine response of the stimulated sample}
  \item{percentile}{numerical value of the threshold; usually the 99.9th
  percentile of the corresponding unstimulated/control sample}
}
\details{
  Specifically \code{\link{percentile.FCS}} is used to obtain the
  percentiles for \code{\link{PercentPos.FCS}}
  and \code{\link{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{\link{createGate}} and \code{\link{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. 
}
\value{
  For \code{\link{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{\link{PercentPos.FCS}}:  
  
  \item{percent.pos}{the fraction of the observations above or equal to
    the threshold/percentile}
  \item{total.num}{total number of observations in the sample}
  
}

\references{Zoe Moodie and Mario Roederer}
\author{A.J. Rossini and J.Y. Wan}

\note{
  Please note that Percentage Positive = 100 * (percent positive).
}
\seealso{ data 'PerPosROC' in \pkg{rfcdorig}
  package, \code{\link{ROC.FCS}}
}

\examples{

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
}

}
\keyword{dplot}% at least one, from doc/KEYWORDS
\keyword{math}