Single simulations

Single simulations are run by calling surveySim(Parameters_List) .

Run your example with: my_sim<-surveySim(my_parameters, plot.artifacts = TRUE) . This will produce the following plot and a list with results.

Example of field map with sites and artifacts plotted

The summary of results can be accessed from the list, like this:

knitr::kable(round(my_sim$Summary,2),caption = "Summary of results for the DIGSS simulations.")

Results for each site and for each site based on artifacts found on survey pits are also stored in the results list:

knitr::kable(round(my_sim$BySite,2), caption= "Results of survey efficiency in detecting sites.")

knitr::kable(round(my_sim$ByArtifact,2),caption= "Results of survey efficiency in detecting sites based on artifacts found in surveys")

Finally, the original parameters used in that simulation are also stored, giving the user the option to access which parameters were used to create the simulation (see them with my_sim$Parameters)

Multiple simulations

Simulations with variable parameters can be run using surveyLoops() . This function allows user to vary one of the parameters across any given sets of values, while keeping all other parameters fixed. This function offers an easy way to check the impact of variation in one of the variables being simulated.

surveyLoop requires a list of parameters (SurveySim class) and a loop variable, which will be a vector or list of vectors with values of one parameter that is to be tested. For details on the format of the loopvariable, see help(surveyLoops) . The function will run one simulation for each value in the loop variable, while keeping all the other parameters constant.

An example to test the impact of variation in the spacing between survey lines can be run like this:

width_loop<-surveyLoops(my_parameters, "col.width",c(50,75,100,125),"sitesFound") .This will produce the following plot and a list with results.

Example of plot comparing multiple simulations with varying distances between survey lines

Results are organized inside a list, as with surveySim(), detailing:

• survey pits per simulation ($surveysPerSim)

• sites found ($sitesFound)

• sites found based on artifact presence in survey pit ($sitesFoundOnArtifacts)

• average number of artifacts per survey pit ($artifactsPerSurvey)

• success rate index (number of survey pits that find a site/total survey pits in the field) ($successRateIndex)

  You can visualize them as follows:

#number of survey pits in each simulation loop
knitr::kable(round(width_loop$surveysPerSim,2),caption="Number of survey pits in each simulation")

#frequency of sites found in each simulation loop
knitr::kable(round(width_loop$sitesFound,2),caption="Frequency of sites found in each simuation")

#frequency of sites found based on artifact in each simulation loop
knitr::kable(round(width_loop$sitesFoundOnArtifacts,2),caption="Frequency of sites found based on presence of artifacts in each simuation")

#average number of artifacts per survey pit
knitr::kable(round(width_loop$artifactsPerSurvey,2),caption="Average number of artifacts per survey pit for each simulation")

#success rate index
knitr::kable(round(width_loop$successRateIndex,2),caption="Success rate index for each simulation")

Comparing simulations

Finally, multiple simulations can be explored visually using plotSurveySumm().

This function will accept the combined results of multiple single simulations and compare them through density plots. The results from multiple simulations must be combined into a list to be passed to the function.

You can run the example in ?plotSurveySumm and get a result similar to this:

Frequency of sites discovered across three different DIGSS simulations

areaEstimator

The real area covered by sites is too complex to be calculated directly, as it may involve the partial overlap of multiple ellipses. Instead, in order to approach the real area coverage of sites, DIGSS uses a cookie-cutter approach. N x N equally spaced points (1000 x 1000 by default) are placed on the survey area and the ratio of points that fall inside at least one site over the total number of points projected returns an approximation of the area. The default values (1,000,000 points) approximates the real area to ~0.1%, which is considered sufficient for the purposes of the simulations.

cloudGenerator

This function generates a cloud of points randomly distributed inside a given ellipse (with known center, angle of major axis, and sphericity). The cloud respects the artifact density provided by user (points/m²) and returns a list of X and Y coordinates for the points.

The basic approach used to place random points is to create points inside of a rectangle defined with dimensions equal to the major and minor axis of the site ellipse, and then remove all the points outside the ellipse’s limit.

For sites with uniform density, this is a very efficient way to generate random points. When density is not uniform, density is selected from a random uniform distribution between min and max values provided by user.

For sites with non-uniform artifact distribution (i.e., linear, spherical, sinusoidal), cloudGenerator adopts an onion-layer approach to approximate artifact density. In these cases, sites will be divided into multiple concentric bands, growing from the center of the ellipse. The number of concentric bands is based on the value of precision (30 by default). For each band, the average density of pieces in it is defined by the respective density function selected based on the distance from the center. Once average density is defined for the band, a rectangle of uniformly distributed points is generated, and only the points that fall inside the band are kept.

This means that the distribution of artifacts is not truly smooth (as it diminishes from the center in a step-wise manner). However, with large enough layers, it approaches a smooth distribution, and maintains the expected property of the cloud of points (i.e., the average density for the site is respected).

This approach, while wasteful (several coordinates created are dropped during function execution), saves time during simulations when executed inside surveySim(). As each concentric band is saved as a different list object, surveySim() only searches for artifacts that fall inside surveys for the bands where the survey pit is located.

fieldMap

This function creates sites of random positions and angles, matching the parameters given to it (site density, site overlap, site area).

Location of sites are based on random X and Y coordinates of ellipses centers taken from a uniform distribution. Rotation of sites are uniformly random. Sphericity is also randomly selected from a uniform distribution, but the lower limit has been arbitrarily fixed as 0.85, so that sites are not too elongated by nature.

Placing of sites happens one at a time, with the coordinates for the new site being checked against previously placed sites to respect the maximum overlap parameter specified by the user. The function will attempt to place a site up to 1000 times, before quitting. If after those attempts, there is no position found for the new site (i.e., the survey area is too filled to accept a new site and respect the overlap parameters), the sites are not placed and the final number of sites returned will have lower site density than expected. A warning message is thrown in these cases.

When site area is not uniform, the area of each site is taken randomly from a normal distribution based on mean and standard deviations provided. Sites will not be smaller or larger than min and max provided, respectively, to curb the presence of outliers (if desired).

surveySim

The main function in the package can be very resource intensive because it uses a brute-force method for counting how many artifacts fall within each survey pit. A few approaches have been implemented to make the function more efficient:

• cloudGenerator() is only called when a survey pit hits a site, and then proceeds to count the number of artifacts in all survey pits inside that site. Data for the site generated is cleared, before moving to the next site.

• The search of artifact coordinates that fall inside each survey pit will be done only within the site band(s) where the pit is located (see cloudGenerator() above).