Population (or cluster) sensitivity

Input Values

This utility calculates a population or cluster level sensitivity for a survey. This is the probability (or level of confidence) that one or more positive units would be detected if the disease was present at a prevalence greater than or equal to the specified design prevalence.

For these calculations unit specificity is assumed to be 100%. For calculating cluster (herd, flock, etc) sensitivity, enter test sensitivity and unit-level design prevalence or for population level sensitivity enter cluster-level (herd) sensitivity and cluster-level (herd) design prevalence.

Calculations use the hypergeometric approximation if population size is provided, or binomial method if population size is not specified.

Inputs are:

• Design prevalence as either a proportion or an integer number of units (animals for cluster level sensitivity and clusters for population-level sensitivity);
• Unit sensitivity (test sensitivity to calculate cluster (herd) sensitivity or cluster (herd) sensitivity to calculate population sensitivity;
• Sample size - the number of units sampled (animals or clusters); and
• Population size (optional if design prevalence is specified as a proportion, required if design prevalence is a number of units). Leave population size blank if not known.

Outputs are:

• Population-level sensitivity for the given sample size, design prevalence and unit sensitivity; and
• A table and graph of population-level sensitivity values for varying population and sample sizes and the given design prevalence and unit sensitivity.

No results

				################################################################
# program to calculate population-level sensitivity
################################################################
# uses RSurveillance package

rm(list = ls())
test<- ifelse(length(commandArgs()) < 3, TRUE, FALSE)
fpath<- ifelse(test, "webRootUrl", "rtoolsPath")

# load header scripts
  source(paste(fpath, "R/epi_head.R", sep = ""))
  source(paste(fpath, "R/HTMLStream.R", sep = ""))
  source(paste(fpath, "R/epitools_functions.r", sep = ""))


# extract command arguments
# pstar, pstar.int, sens, n, N (if known), 
    a1<- type.convert(a0[8:11])


# initialise variables
pstar<- a1[1]
pstar.int<- ifelse(pstar < 1, F, T)
Sens<- a1[2]
n<- a1[3]
N<- a1[4]
digits<- 4
filename<- as.numeric(Sys.time())
graphfile<- paste(fpath, "tmp/", filename, ".png", sep="")
sinkfile<- paste(fpath, "tmp/", filename, ".txt", sep="")

# check for valid sample size
if (n > N & N > 0) {
    cat("Sample size exceeds Population size. Please try again.")
    quit()
}


sink(sinkfile)

# table of inputs
inputs<- array("", dim = c(length(a1), 1))
inputs[, 1]<- a1
rownames(inputs)<- c("Design prevalence (Pstar)", "Unit (test or cluster) sensitivity", "Sample size (n)", "Population size (N)")
if (N <= 0) inputs[4, 1]<- "Unknown"
if (pstar.int) inputs[1,1]<- paste(pstar, "units") else inputs[1,1]<- paste(pstar*100,"%", sep = "")
if (N <= 0) N<- NA

seh<- round(sep(N, n, pstar, Sens), digits)

results1<- rbind(inputs, "Population (cluster or system) sensitivity" = seh)

n.levels<- c(5, 10, 15, 20, 30, 50, 75, 100, 200, 300, 500, 1000)
N.levels<- c(50, 100, 200, 300, 500, 1000, 5000, 10000, 100000, 1000000)
results2<- array(NA, dim = c(length(N.levels), length(n.levels)))
for (i in 1:length(n.levels)) {
  for (j in 1:length(N.levels)) {
    if (n.levels[i] <= N.levels[j]) results2[j, i]<- round(sep(N.levels[j], n.levels[i], pstar, Sens), digits)
  }
}
colnames(results2)<- c(paste("n = ", n.levels, sep = ""))
rownames(results2)<- c(paste("N = ", format(N.levels, scientific = F), sep = ""))
n.lines<- length(N.levels)
# cat(test)

# graph results
    Title<-"Population sensitivity for varying sample and population size"
    OpenGraphOutput(graphfile, pointsize = 12, ht = 6, wd = 8)
    line.colours<- c("darkblue", "red", "darkgreen", "magenta", "brown", "purple", "black", "blue", "darkred", "tan")
    plot(x = n.levels, y = results2[1,], type="n", ylab = "Population sensitivity", ylim = c(0, 1),
                xlab="Sample size", main=Title, col = line.colours[1])
    for (i in 1:n.lines) {
        lines(x = n.levels, y = results2[i,], type = "l", col = line.colours[i])
    }
    legend.txt<- rownames(results2)[1:n.lines]
    legend("bottomright", legend.txt, 
        col = line.colours, lty = c(1, 1), plot = TRUE, cex = 0.7)
    CloseGraphOutput("R")
sink()
# cat(test)

# add infinite population if appropriate
if (!pstar.int) {
  seh.inf<- round(sep.binom(n.levels, pstar, Sens), digits)
  results2<- rbind(results2, "N = inf" = seh.inf)
}
results2<- formatC(results2, digits = digits)

# write to html and file
heading<- "Population or Cluster level sensitivity"
subheadings<- c("", paste("Population sensitivity for varying sample and population size (Se = ", Sens, ", PStar = ", inputs[1], ")", sep = ""))
tmp.file<- paste(fpath, "tmp/", filename, sep = "")
output<- html.output(heading, subheadings, "", results = list(results1, results2), graphs = graphfile, graph.headings = "", show.inputs = F, show.graphs = T, tmp.file, result.txt = "") 
write.html(output, tmp.file)
cat(output)