########################################################################
Conduct the Monte Carlo Simulations to Obtain the Overall Clustering for 
the Cluster Detection Based on Cases
########################################################################

DESCRIPTION: 

For specified cluster sizes and results from case.test, conducts the 
simulations for the overall clustering based on cases. 


USAGE: 

sim.case.calc(kmat,datmat,popmat,nnmat,resultmat,numsim,signiflevel=0.05,print.it=F)


REQUIRED ARGUMENTS: 

kmat 
     the cluster sizes used for the testing. If a vector, each element corresponds to 
     the cluster size for each cell (has dimension equal to the total number of cells). 
     If kmat is a matrix, each row contains the sequence of cluster sizes to test for 
     each cell. The testing algorithm is employed if kmat is a matrix. Each cluster 
     size must be > 1.
datmat 
     the matrix containing the number of cases in each cell (rows) by each stratum 
     (columns).
popmat 
     the matrix containing the number of population in each cell (rows) by each 
     stratum (columns).
nnmat 
     the square matrix containing the ordered nearest neighbours: 
     nnmat[i,1]=i, nnmat[i,j]=cell i's (j+1)th nearest neighbour. Assumes that the 
     cells are indexed (labelled) from 1 to the total number of cells.
resultmat
     the matrix of results output from case.test.
numsim
     the number of simulations to conduct.


OPTIONAL ARGUMENTS: 

signiflevel
     the significance level for each cluster test. The default is 0.05. 
print.it 
     a flag to indicate if intermediate calculations should be printed (print.it=T) 
     or not (print.it=F). The default is print.it=F.


VALUE: 

a p-value for the overall testing. Prints out the frequency distribution 
of the number of significant clusters in the simulations.


DETAILS:

This method is based on the Besag and Newell (1991) test statistic. The testing 
algorigthm is based on Le, Petkau, and Rosychuk (1996). 


EXAMPLES: 

#hypothetical 10 cell region
#provide the nearest neighbour for cells 1 to 10
nnEx=matrix(scan(),ncol=10,byrow=T) 
 1  5  2  3  9  4 10  6  7   8
 2  3  5  4  1  8  9 10  6   7
 3  2  4  5  1  8  9 10  6   7
 4  3  2  5  8  6  7  1  9  10
 5  2  3  4  1  8 10  9  6   7
 6  7  4  8  3  2  5 10  9   1
 7  6  8  4  3  2  5  9 10   1
 8  4 10  7  3  6  2  1  5   9
 9 10  7  6  4  5  2  1  3   8
10  9  7  8  6  4  5  2  1   3

#population data with 2 strata
popEx=matrix(scan(),ncol=2,byrow=T)
 1358  1405
 1005  1089
  117   120
   66    62
 2827  2749
  152   158
   16    26
   67    92
 1456  1444
  174   180

#case data with 2 strata
datEx=matrix(scan(),ncol=2,byrow=T)
    3     2
    0     0
    0     0
    2     0
    2     3
    0     0
    0     0
    0     0
    1     1
    0     0

#do the testing with user supplied cluster sizes
kEx=rep(2,10)#test each cell at cluster size=2
resultEx=case.test(kEx,datEx,popEx,nnEx)

#run the simulation 10 times for the overall test
pEx=sim.case.calc(kEx,datEx,popEx,nnEx,resultEx,10)

#output of the results
#Simulation results:
#Frequency of the number of clusters identified:
#     0 1 2 3 4 5 
#[1,] 8 2 0 0 0 0
#Number of sims= 10   Number of sims > 2 = 0   pvalue= 0 
print(pEx) #print the pvalue
#[1] 0