surveySim {DIGSS}

Survey Simulations

Description

Master function that runs survey simulations

Usage

surveySim(
  survey.parameters,
  artifact.analysis = TRUE,
  plot = TRUE,
  plot.artifacts = FALSE,
  areaprecision = 1000
)

Arguments

survey.parameters

List of class surveySim. See package's vignette or the help of parametersExample for details. The following items must be included in list of class surveySim

• col.width the space between columns in the grid IN METERS

• grid.type options are: "square","rectangle","staggered","hexagonal","arbitrary.staggered", following Kintigh 1988

• simulations number of random maps to be created and contrasted with the grids

• area vector with horizontal and vertical size of area surveyed in km OBS: Sites will all be ellipses with radii not too different and random angles

• site.density measured as number of sites/km². Can be either one value or a vector with 2 values (min and max) to create a range of densities

• site.area can be one of two options: 1. one value indicating the area of all sites, in m²; or 2. a vector with 4 values: min, max, mean (or median), and standard deviation in m²

• overlap maximum overlap of site area, ranging from 0 = no overlap allowed to 1 = complete overlap possible

• obj.density artifacts per m². Can be a single value (uniform for all sites) or a range of values defined as min and max

• obj.distribution type of cloud distribution for artifacts inside sites. Choose from: 'uniform', 'linear', 'spherical', 'sinusoidal'

• survey.radius the radius of the survey pit (assumed to be a circle)

artifact.analysis

Includes the analysis of artifacts in sites. Can be very time-consuming for mid-high artifact densities. Default = TRUE

plot

If TRUE the last iteration of the simulations will be plotted.

plot.artifacts

If TRUE the artifacts in each site will be plotted. Default = FALSE because it is resource intensive for mid-high densities.

areaprecision

Area covered by sites is approximated by a cookie-cutter approach. Default precision = 1000 gives approximate area within 1% error. Higher values reduce error but are more resource intensive.

Details

surveySim() is the main function that will conduct the simulations of survey grids based on the Survey Parameters created by user.

Value

A list with four objects:

Summary	A matrix with summary statistics about number of surveys, frequency of site founds, artifacts presence, and success rate of simulations.
BySite	A matrix with results of the analyses by site from each of the survey areas created in the simulation.
ByArtifact	A matrix with results of the analyses by artifact presence in survey pits from each of the survey areas created in the simulation.
Parameters	A list with the parameters used to run the simulation.

#'@references Kintigh (1988) The Effectiveness of Subsurface Testing: A Simulation Approach. American Antiquity, 53:686-707. doi: 10.2307/281113

Examples

#Runs simulations based on parametersExample
surveyExample<-surveySim(parametersExample)

#Edit parametersExample to have 50 simulations and then run simulations
tmp_parameters <-parametersExample
tmp_parameters$simulations<-50
survey50<-surveySim(tmp_parameters)