R/SampleSize.R

In ryanmismith/inventoryfunctions: Forestry Inventory Functions

#' Sample Plot Allocation
#'
#' This function calculates the number of samples that should be assigned to a particular strata. Designed for forestry applications.
#' This function utilizes area, variance, and a particular value of interest to determine sample plot allocations.
#'
#' The weighted value can be anything the user decides is of the most value
#' ex: Basal area, Volume, Percentage Hardwood, etc. The estimated
#' variance of this value within each strata can also be used for weighting sample plot allocations.
#' The user can choose to ignore any of the inputs by entering the value 1.
#' See examples for and example where no particular value of interest is used,
#' for an example where the CV within each strata is not estimated,
#' and an example where both a value of interest and the CV are ignored.
#'
#'@param Strata A vector of Strata names or IDs. Each value will be treated as a unique strata even if names are repeated.
#'@param Area The area of each strata. This can be in any unit desired by the user.
#'@param CV The estimated coefficent of variation for each Strata of the value of interest.
#'@param Value The value of significance that will be used as a weight for sample size suggestions
#'@param TotalSamples A single number that equals the total number of samples you wish to take.
#'
#'@return A dataframe with the strata and suggested number of samples for each strata
#'
#' The minimum number of samples that will be assigned to a strata is 3. This allows
#' the calculation of a mean, sd, etc. This will sometimes lead to a sum of the total
#' samples suggested to be slightly larger than the TotalSamples value entered by the user.
#' When this occurs a warning will be printed along with the dataframe output.
#'
#'@examples
#'
#' Strata <- c("MA", "f",  "g",  "pr", "tw", "fr")
#' Area <- runif(6, min = 100, max = 1000)
#' CV <- runif(6, min = 20, max = 80)
#' Volume <- runif(6, min = 8, max = 42)
#' TotalSamples <- 100
#'
#'
#' SampleSize(Strata, Area, CV, Volume, TotalSamples)
#' SampleSize(Strata, Area, CV, 1, TotalSamples) # no value of interest is included. TotalSamples is a vector of length 1.
#' SampleSize(Strata, Area, 1, 1, 120) # no value of interest and no estimate of variance, area only value utilized.
#' SampleSize(Strata, Area, 1, Volume, 25) # No estimate of variance is used.
#' Samples <- SampleSize(Strata, Area, CV, Volume, TotalSamples) # Strata names and samples can be saved to a dataframe.
#'@export



SampleSize <- function(Strata, Area, CV, Value, TotalSamples){


  TSamples <- rep(TotalSamples, length(Strata))           # Create vector for Sample Size Calcs
  Data <- data.frame(Strata, Area, CV, Value, TSamples)           # Create DF to bring all vectors together


  for (i in 1:length(Data$Area)){                           # Create a Weight for each Strata
    Data$Weight[i] <- Data$Area[i]*sqrt(Data$CV[i]^2*Data$Value[i])
  }

  TotalWeight <- sum(Data$Weight)                            # Get Total Weight
  Data$TotalWeight <- rep(TotalWeight, length(Strata))  # Create vector for Total Weight Calcs

  for (i in 1:length(Data$Weight)){
    Data$Samples[i] <-  (Data$Weight[i]/Data$TotalWeight[i])*Data$TSamples[i]
  }

  Data$Samples <- round(Data$Samples, 0)
  Data$Samples <- ifelse(Data$Samples < 3, 3, Data$Samples)
  x <- data.frame(Data$Strata, Data$Samples)

  colnames(x) <- c("Strata", "Samples")

  if(sum(x$Samples) > TotalSamples){
    print("At least 3 Samples required for all Strata, Decrease Total Samples if this creates a Sample Size that is too Large")
  }


  return(x)

}