\HeaderA{make.grid}{Make a matrix of values allocated in a two dimensional grid}{make.grid}
\aliasA{make.density}{make.grid}{make.density}
\keyword{manip}{make.grid}
\keyword{hplot}{make.grid}
\begin{Description}\relax
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
\LinkA{image}{image} or \LinkA{ContourScatterPlot}{ContourScatterPlot} plot can be implemented.
\end{Description}
\begin{Usage}
\begin{verbatim}
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"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a vector of data values for the x-axis 
\item[\code{y}] a vector of data values for the y-axis
\item[\code{status}] a vector of 0, 1 values denoting two categories
\item[\code{x.grid}] a vector of grid marks to allocate x
\item[\code{y.grid}] a vector of grid marks to allocate y
\item[\code{type.CSP}] character string denoting the type.CSP of value to be
estimated using the 'status' for each cell grid
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The following details the options for 'type.CSP':

\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.  
\end{Details}
\begin{Value}
\begin{ldescription}
\item[\code{z}] matrix of values corresponding to the counts in an x-y grid
\item[\code{n.cells}] (only output for 'make.grid'); number of total observations in z
\item[\code{type.CSP}] (only output for 'make.density'); the type.CSP of value in each cell.
\end{ldescription}
\end{Value}
\begin{Note}\relax
In the base package, the function \code{\LinkA{image}{image}} could make a
plot with the resulting matrix of values.
\end{Note}
\begin{Author}\relax
Zoe Moodie, A.J. Rossini, J.Y. Wan
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{image}{image}}, \code{\LinkA{ContourScatterPlot}{ContourScatterPlot}},
\code{\LinkA{pairs.CSP}{pairs.CSP}}, \code{\LinkA{legend.CSP}{legend.CSP}}, \code{\LinkA{heat.colors}{heat.colors}}
\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)
  }

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

}
}

\end{ExampleCode}
\end{Examples}

