saSampleAlloc: Optimal Allocation Using Simulated Annealing
In jlisic/saAlloc: Optimal Allocation of Sampling Units to Form Strata using Simulated Annealing

Description Usage Arguments Value Examples

This function exchanges sample allocations between strata to minimize the CV of a set of known administrative variables. This is accomplished by through simulated annealing, where proposed changes in allocations are accepted or rejected based on a penalized objective function. The penalized objective function takes the form of the sum of an L2 norm and a penalty function. The first L2 norm is the vector of differences between the CVs for the current allocation and the target CVs. The penalty function is the dot product between a vector of penalty values and the vector of CVs for the current allocation.

saSampleAlloc(
  total,
  S2,
  targetCV,
  sampleSize,
  strataSize, 
  locationAdjustment,
  scaleAdjustment,
  iterations=100,
  p = 2,                   # l2 norm of the penalty function
  penalty = -1,            # negative penalties are ignored
  cooling = 0,
  preserveSatisfied=TRUE,
  fpc = TRUE
   )

`total`	(Required) A matrix where each row is a replicate population total and each column is a characteristic of the sampling population used for allocation. When replicates are used, the average CV of each characteristic is used in the objective function.
`S2`	(Required) A matrix where each row identifies a stratum (in order) and each column is a characteristic of the sampling population used for allocation. The values of this matrix is the variance estimate for each sampling unit within each stratum (S^2). When replicates are used for total, a variance must also be provided for each replicate. This is done by appending each replicate matrix of variances to the S2 matrix in the same order it appears in total.
`targetCV`	(Required) A vector of target CVs. This vector must be of equal length to the number of columns of `total`.
`sampleSize`	(Required) sample size, either an integer valued scalar that will be equally split between strata, or a sample size for each strata. When the sample size cannot be split excess sample allocations will be given to strata in increasing order.
`strataSize`	(Required) strata size, an integer valued array or population sizes by stratum.
`locationAdjustment`	A constant value added to the population variable for each administrative variable, this is of the same size and layout of `S2`.
`scaleAdjustment`	A constant value multiplied by the population variable (before the location adjustment) for each administrative variable, this is of the same size and layout of `S2`.
`iterations`	Number of iterations of the allocation.
`p`	The exponent for the penalty function, fractional exponents are available.
`penalty`	The penalty vector used for each of the CV targets penalties. Penalties with negative elements are ignored. A scalar value may be used, and will be repeated for all CVs.
`cooling`	Cooling Schedule (0 = exchange only).
`preserveSatisfied`	`TRUE` implies that any constraint that is met for an accepted state is kept, `FALSE` allows for met CVs to be violated by accepted states.
`fpc`	`TRUE` use a finite population correction factor (fpc), `FALSE` do not use a fpc.

`accept`	Matrix with three columns and a row for each iteration, "change": change in objective function, "U": uniform random variable, "accepted": 1 - accepted, 0 - not accepted "selected": index of PSU, "from": current stratum of selected PSU , "to": candidate stratum of selected PSU, "n_h": sample size (h is the index or label associated with strata), column names or numbers if not presented
`cost`	Objective Function
`label`	Final Label
`sampleSize`	Final Sample Size

# data set with 100 observations and four 
# characteristics split between two strata
x <- matrix(rnorm( 100*4 ),ncol=4)  

total <- colSums(x)

S2 <- apply( x, 2, var)

# run minCV for a sample size of 20
b <- saSampleAlloc(
  total,
  S2,
  strataSize=rep(50,2),
  targetCV=c(0.08, 0.10, 0.05, 0.08),
  sampleSize=20
)

summary(b)