\name{make.grid}
\alias{make.density}
\alias{make.grid}
%- Also NEED an `\alias' for EACH other topic documented here.
\title{Make a matrix of values allocated in a two dimensional grid}
\description{
  A two-dimensional plot can be subdivided via grid
  marks and lines.  Each component of the resulting
  grid is called a cell.  The function \code{make.grid}
  determines a matrix of values corresponding
  to the number of observations that lie
  within each cell of the grid.  The function \code{make.density}
  estimates the values allocated to each grid cell by a 'status' binary
  variable.  The values are estimated to be either a difference in
  counts between the two status categories, a proportion, a normalized
  proportion, and a z statistic for each cell such that an
  \link{image} or \link{ContourScatterPlot} plot can be implemented.
}
\usage{
make.grid(x, y, x.grid = seq(0, 1025, by = 25),
           y.grid = seq(0, 1025, by = 25))

make.density(x, y, status = NULL,
          x.grid = seq(0, 1025, by = 25),
          y.grid = seq(0, 1025, by = 25),
          type.CSP = c("count.diff", "p.hat", "p.hat.norm", "z.stat"))
}
%- maybe also `usage' for other objects documented here.
\arguments{
  \item{x}{a vector of data values for the x-axis }
  \item{y}{a vector of data values for the y-axis}
  \item{status}{a vector of 0, 1 values denoting two categories}
  \item{x.grid}{a vector of grid marks to allocate x}
  \item{y.grid}{a vector of grid marks to allocate y}
  \item{type.CSP}{character string denoting the type.CSP of value to be
    estimated using the 'status' for each cell grid}
}

\details{
  The following details the options for 'type.CSP':
   \describe{
  \item{"count.diff"}{The cell value is the count difference between the two 'status'
    categories}
  
  \item{"p.hat"}{The grid cell value is the proportion of observations
    with 'status'==1 for that grid cell.}

  \item{"p.hat.norm"}{The grid cell value is the following:

    (ie, (p.hat -  0.05)/sqrt( (0.05 * (1-0.05)) /n))
    
    p.hat is the proportion in 'status'==1
    
    where n is the number of cells in the grid with information.  The
    default is to set the z statistic to zero for the cells
    with no information in either status.  The value 0.5 is considered
    to be the case of no difference when the counts of both categories
    of 'status' are the same in the grid cell.
    }
    
  \item{"z.stat"}{The cell value is a z statistic computed as the
    following:
    
    (ie, (p.hat -  p.bar)/se(p.bar))
    
    p.hat is the proportion in 'status'==1
    
    p.bar is the average of p.hat over the whole grid
    
    se(p.bar)=sqrt((1-p.bar)(p.bar)/n),
    where n is the number of cells in the grid with information.  }
    }

}

\value{
  \item{z}{matrix of values corresponding to the counts in an x-y grid}
  \item{n.cells}{(only output for 'make.grid'); number of total
  observations in z} 
  \item{type.CSP}{(only output for 'make.density'); the type.CSP of
  value in each cell.} 
 
}

\author{Zoe Moodie, A.J. Rossini, J.Y. Wan}
\note{In the base package, the function \code{\link{image}} could make a
 plot with the resulting matrix of values.}



\seealso{ \code{\link{image}}, \code{\link{ContourScatterPlot}},
  \code{\link{pairs.CSP}}, \code{\link{legend.CSP}},
  \code{\link[grDevices:palettes]{heat.colors}}
} 

\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)
  }

var1<-st.DRT@data[,4]
var2<-st.DRT@data[,5]
var1.2<-unst.DRT@data[,4]
var2.2<-unst.DRT@data[,5]

col.nm<-colnames(st.DRT@data)

## The status where 1=stimulated
## 0 = unstimulated
status<-c(rep(1, dim(st.DRT@data)[1]), rep(0, dim(unst.DRT@data)[1]))
x <- c(var1, var1.2)
y <-c(var2, var2.2)


count.output1<-make.grid(var1, var2)
count.output0<-make.grid(var1.2, var2.2)

## matrix of counts
mat.counts1<-count.output1$z
mat.counts0<-count.output0$z
##total observations
total.stimulated<-count.output1$n.cells
total.unstimulated<-count.output0$n.cells


count.diff.output <-make.density(x, y, status=status, type.CSP="count.diff")
## matrix of cont differences between the status categories
mat.count.diff <-count.diff.output$z

p.hat.output <-make.density(x, y, status=status, type.CSP="p.hat")
## matrix of cont differences between the status categories
mat.p.hat <-p.hat.output$z

p.hat.norm.output <-make.density(x, y, status=status, type.CSP="p.hat.norm")
## matrix of cont differences between the status categories
mat.p.hat.norm <-p.hat.norm.output$z

z.stat.output <-make.density(x, y, status=status, type.CSP="z.stat")
## matrix of cont differences between the status categories
mat.z.stat <-z.stat.output$z

if (interactive()){
par(mfrow=c(3,2))


image(mat.counts1,yaxt="n", xaxt="n",
  main="make.grid: Counts for stimulated",
   xlab=col.nm[4],
   ylab=col.nm[5], col=heat.colors(20))

image( mat.counts0,yaxt="n", xaxt="n",
  main="make.grid: Counts for unstimulated",
   xlab=col.nm[4],
   ylab=col.nm[5], col=heat.colors(20))

image( mat.count.diff,yaxt="n", xaxt="n",
  main="make.density: Count Difference (Stimulated-Unstimulated)",
   xlab=col.nm[4],
   ylab=col.nm[5], col=heat.colors(20))

image( mat.p.hat,yaxt="n", xaxt="n",
  main="make.density: Proportion of Stimulated",
   xlab=col.nm[4],
   ylab=col.nm[5], col=heat.colors(20))

image( mat.p.hat.norm,main="make.density: Normalized proportion of Stimulated",
   xlab=col.nm[4],yaxt="n", xaxt="n",
   ylab=col.nm[5], col=heat.colors(20))

image( mat.z.stat, main="make.density: z statistic",
   xlab=col.nm[4],yaxt="n", xaxt="n",
   ylab=col.nm[5], col=heat.colors(20))

}
}

}
\keyword{manip}% at least one, from doc/KEYWORDS
\keyword{hplot}% __ONLY ONE__ keyword per line