Beginners Interactive NetLogo Dictionary (BIND)
Farsi / Persian
NetLogo User Community Models
## WHAT IS IT?
## HOW IT WORKS
You first seed a simple "landscape" with a random, clustered, or a mixed distribution of "artifacts" (but these could be sites or anything else in practice). You then create a sampling frame with set of sampling patches either by randomly distributing them, uniformly laying out on a grid or transect, or by judgmentally placing them by clicking on the map. You can combine techniques for a "stratified" or "mixed" approach as well. Finally, the program will then count up the number of "artifacts" that were detected, calculate the sample positivity rate, sample density, and the statistically extrapolated estimate of the total number of "artifacts" that would be predicted from the sample (among other measures). A "good" sampling strategy for a given distribution of artifacts would predict an extrapolated count that closely matches the actual total number of artifacts that were seeded across the landscape.
The landscape consists of a 50 x 50 grid of survey patches (2500 total landscape patches). The simulated survey landscape is scale-free, so there is no specific spatial scale to the patches. It may, however, be useful to imagine the landscape at a familiar scale, such as a series of 1x1 meter grid squares, to help you visualize these results in a "real world" context.
## HOW TO USE IT
There are two ways to use this model: 1) "Manual" mode, or 2) "Iterative" mode. Manual mode is useful for simple experiental experimentation, teaching and learning, or when setting up a more complex set of experiments. You can get a quick inital sense of the comparative utility of different potential sampling frames for different types of artifact distributions. Iterative mode, on the other hand, allows the deployment of an iterative sampling experiment that can provide robust statistical quantification of the performance of different sampling frames with different artifact distributions. It can also help you to understand and quantify the expected error of any specific style of sampling with different types of artifact distributions. Workflows for both modes are explained here.
For either Manual or Iterative operation of the model, you must first click the *Start/Reset Experiment* button to set up a blank landscape before conducting any experimentation. Note that this button can also be used to clear all existing distributions, sampling frames, and results once you've started using the model.
### Manual Mode
All of the tools for Manual Mode appear to the left side of landscape window (i.e., the "world" display in NetLogo terminology).
For manual experimentation, you must first set up the artifact distribution using the *Setup artifact distribution* button in conjunction with a series of parameters related to the type of distribution you desire. The *num_artifacts* sets the total number of artifacts, and the *artifact_clustering* slider sets up the way they are distributed across the landscape. If *artifact_clustering* is set to 0, then a true Gaussian random distribution of artifacts is used. If set to 1 or higher, then artifacts are randomly distributed within neighborhoods around a set of cluster centers. The number of cluster centers is the same as the value set by *artifact_clustering* (i.e., *artifact_cluster* of 5 will make 5 clusters, etc.). The size and shape of the cluster neighborhoods are determined with the "cluster_x" and "cluster_y" sliders in number of cells per dimension. Use the *Setup Artifact Distribution* button to place the artifacts. Clusters are initially created within square areas. You can create more natural shapes to the clusters using the *Shuffle artifacts* button. This button activates a 20-tick "random walk" for all artifacts, which effectively "jitters" their location within a 20-cell radius. This button could be used more than once if necessary.
Note that you can change the artifact distribution settings and click the *Setup artifact distribution* button again to superimpose different distributions. This is useful, for example, to create mixed random background scatter with clusters of artifacts. You can click the *Clear artifact distribution* to erase any previous distributions. Note that for some values of *artifact_clustering*, the actual number of artifacts may be automatically adjusted to evenly divide artifacts across clusters. To display the actual count of seeded artifacts, you can at any time click the *Count Survey Patches/Artifacts* button.
At this stage, you can choose to save out your artifact distribution so that you can load it in at another stage (e.g., in order to repeat your experiments again). To do so, go to the File menu in NetLogo, and choose *Export > Export World...*. Give a descriptive name for the output .csv file so that you will know what kind of distribution is in it. Note that this also exports the current state of any sliders or switches, so ensure that all of those are set to a neutral or otherwise desired position to avoid future mistakes. To reimport the distribution, go to the File menu and choose *Import > Import World...*, and choose the file you exported previously.
Once the artifacts are distributed, you can optionally use the *hide some artifacts* button in conjunction with the *proportion_hid* slider to hid a portion of the artifacts from view. This would allow you to, for example,use the distribution of a small proportion of "surface" artifacts when planning a "shovel test" grid, which will then be used to prospect for buried artifacts as well. You could even choose to hide all artifacts, and then layout a grid with no a priori knowledge of artifact locations at all. It is, therefore, a useful tool for limiting the impact of bias when setting up your survey patches.
Next you will need to set up your survey patches. There are three tools that you can use for this, and they can be used separately or in any combination. As you add survey patches, they will turn blue on the map.
The *Select n random survey patches* tool works in conjunction with the *n* slider to randomly distribute some number of survey patches around the landscape.
The *Setup a systematic grid of survey patches* button is used in conjunction with four other sliders to create an evenly distributed sampling grid with survey patches at the grid intersections. The value of *grid_x* is the number of patches between each survey patch in the x direction, and the value of "grid_y" is the number of patches between each survey patch in the y direction. The *x_offset* and *y_offset* sliders set the distance (in # of patches) of the lower left survey patch from the lower left corner of the landscape. It is important the values for x and y offsets be lower than the values for the grid x and y dimensions, respectively. These four sliders can be used together to position your survey grid very precisely.
The *Interactively select survey patches* button is used to interactively click on patches on the map to select them as survey patches. This can be used to create a "judgemental" sampling strategy, where you use your prior knowledge to choose the location of each sampling patch. This button is a "latching" button, so you must "unclick" it once you've finished your selection of judemental survey patches.
Once you have selected your patches, you can optionally click the *Count survey patches/artifact* button to quickly count the number of survey patches you've created. This is useful if you need to constrain the number of patches for your experiment (e.g., you are limited by time or budget to a set maximum number of survey patches). You can also use the *Reset survey patches* button to return all survey patches to a blank (blue) state. This is useful if you want to use the same survey sampling frame with a new artifact distribution. Alternatively, you can use the *Clear survey patches* to delete your current set of surve patches so that you can design a new one. This is useful if you've made a mistake, gone over your survey patch limit, or if you want to keep the same artifact distribution, but test different survey patch arrangements.
Once your artifact distribution and survey patches are set up, you can use the *Display Results!* button to quickly calculate a series of summary statistics and to change the color of the positive survey patches to green, and negative patches to red. There is one variable that you can set in this area, which is the *density_thresh* variable. The value you enter here will determine which survey patches are thought to be in a dense area of artifacts. If the count within a positive survey patch is greater than or equal to *density_thresh*, then the color of that patch will turn to cyan, and the total number of positive patches in "dense" areas will be counted.
### Iterative Mode
The additional tools for Iterative Mode are on the right side of landscape window. There are three buttons, one text entry box, and five switches. You must first create or load in an existing artifact distribution. You can create a new distribution as described in Manual Mode above, and you can save and reload an existing distribution with the Export World and Import World options in the File menu as described above.
To run an experiment, use the Manual Mode sliders to parameterize a random or a systematic sampling frames as described in Manual Mode, and then use the switches to turn on various aspects of the iterative sampling procedure. The *iterate_random* switch will create a series of random sampling surveys with *n* survey patches. The *iterate_grid_size* switch will create a series of systematic grid-based sampling surveys where the x and y spacing of the sampling grid will vary randomly between 0 and the values set by *grid_x* and *grid_y*. The *iterate_grid_offset* switch will create a series of systematic grid-based sampling surveys where the offset from the lower left corner will randomly be chosen between 0 and the values set by *grid_x* and *grid_y*. Note that these three switches are *not* mutually exclusive! You can have all three enabled, and this will potentially produce very complex combinations of random and systemic grid-based sampling frames. This may produce undesired behavior, so it is important ot carefully check both the status of these three switches *and* the state of the sliders on the left side of the landscape window before proceeding.
A fourth switch, *random_n* allows for a random number of patches (randomly chosen between 1 and the value of "n" set by the *n* slider) to be selected at each tick during iterative use of the model. When unchecked, the number "n" is fixed at the value set by the slider *n* so that a fixed number "n" of random patches is selected at each tick during iterative use of the model. This is useful, for example, for determining the smallest number of random survey patches that can still provide a robust sampling result. Note that *random_n* only has an effect when the *iterate_random* switch is also set to "on."
The fifth and final switch, *square_grid*, will instruct the model to only use the *grid_x* variable for both the x and y dimensions when setting the grid size if *iterate_grid_size* is also checked. This will ensure that all the sampling grids created in the iterative grid size changing routine will only be square in shape.
At this point you can start to run your experiment. To manually step through a series of iterations, you can click the "Step" button as many or as few times as you would like. Each click of the *Step* button will advance the tick counter by one. The latest sampling frame and results will be shown in the landscape window and output areas, respectively. If you would like to quickly run through a set number of iterations, you can enter the total number of iterations desired into the *iterations* text entry box, and then click the *Iterate!* button. You will see the tick counter automatically advance, and the landscape window and output area will rapidly change with the various scenarios and results.
The output area at the bottom of the window will create a new line of statistics for each iteration of your experiment. When the experiment is complete, you can save this out either by right clicking on the output area and slecting *Export...* or by going to the File menu, and selecting *Export > Export output...*.
To quickly proceed with a new sampling experiment while keeping the current artifact distribution loaded in, you can click the *Reset Iterations!* button. Note that this will clear the output area, so be sure that you have saved out that data if you wish to keep a record of your previous experimental results. If you would like to start completely fresh, you can use the *Start/Reset Experiment* button on the left side of the window, which will also blank out the artifact distribution.
### Summary statistics
Summary statistics are shown on the bottom left side in labeled output boxes, and formatted as comma-delimited text in the bottom text output window. They include (note that some of these are only inlcluded in the formatted text output window):
- The sample size (% of the total landscape that was surveyed)
The count of survey patches and total number of artifacts are also updated if you have not yet used the "Count survey patches/artfiacts" button.
The extrapolated count is calculated as the number of artifacts discovered in the current sampling frame divided by the sample size (percent of landscape covered). If this number is close to the actual number of seeded artifacts (*num_artifacts*), then it can be concluded that the sampling strategy is effective. The "Count difference" output window shows you this comparison, and similarly, the "Density difference" output window shows you the difference between the calcualted artifact density in the sampling frame versus the true density of artifacts in the total landscape.
Finally, note that there is an output text window at the very bottom of the screen that will keep a running tally of all the results that are calculated each time you click the "Display Results!" button, the "Step" button, or the "Iterate" button. If you are using the model for statistical analysis or comparison, this formatted text area will help you export all of the salient information you will need. The text in this window is formatted as comma-delimited columns with a header row of column labels. This means that it can be directly imported (or copied and pasted) into a standard spreadsheet or other statistical analysis software. You can quickly save out the entire contents of the output window either by right clicking on the output area and slecting *Export...* or by going to the File menu, and selecting *Export > Export output...*. By default, the text export will be saved with a ".txt" file suffix, but you can change this to ".csv" for simpler import into your favorite spreadsheet program. At any point, you can clear and reset the output window by clicking the *Clear output window* button that appears just to the left of the output window.
## THINGS TO TRY
Set up a single artifact distribution, and then create a series of different sampling frames using the "Clear survey patches" button each time to blank out the previous sampling frame. This tests the effectiveness of different sampling frames for one type of artifact distribution
Set up a single sampling frame, and then create a series of different artifact distributions using the "Clear artifact distribution" and "Reset survey patches" buttons. This can test the effectiveness of a single sampling frame on multiple types of artifact distributions.
Try iteratively increasing the number of survey patches, and note how the extrapolated prediction changes. Is it possible to "under sample" and get a prediction that is too small? Is it possible to "oversample" and get a prediction that is too large? Are you ever able to predict the exact number of artifacts? How big is the window of sample sizes where predicted results are reasonably accurate?
Try combining survey sampling strategies. You can, for example, create a "stratified random" sampling strategy by combining an overall random distribution with some interactive (but randomly chosen) "clicked" sampling patches in a specific part of th map.
Try increasing the artifact cluster size. As it gets larger and larger, the distribution of seed artifacts approaches a uniform distribution.
Experiment with the artifact cluster number and dimensions set by "cluster_x" and "cluster_y". By carefully superimposing different types and sizes of artifact clusters, you can create very realistic "palimpsests" of activity areas, occupational phases, or regional site histories. You can also superimpose a sparse "background scatter' of artifacts by setting "num_artifacts" to a small number, and choosing 0 clusters for a random distribution.
You can create continuous linear survey "transects" in the x or y direction by setting one of "grid_x" or "grid_y" to 1. You would want to set the cooresponding "offset" slider to 0 (e.g., if you set "grid_x" to 1, then also set "x_offset" to 0) if you wanted your transects to cross the entire length or breadth of the landscape. The transect spacing and locations would then be controled by the value you set in the other grid dimension and offset.
Use the iterate controls on the right side of the landscape window to automatically step through various types of sampling frames. This can give you a statistical sense of the effectiveness of your potential sampling system.
## EXTENDING THE MODEL
The gridded sampling frame is only available as a rectangular grid oriented orthogonally to the landscape grid. It would be useful to add the functionality for the sampling grid to be rotated obliquely to the landscape grid, and for the ability to design triangular or hexagonal grids. In the same way, artifact clusters can only be oriented in the x and y directions. It would be useful to allow them to be rotated as well, although this can be approximated using the grid spacing variables (but the actual orentation of the square patches remains orthagonal to the world frame). It would require a more complex setup routine. Finally, the iterative version of the model only alters the sampling frame, but not the artifact distribution. Therefore, the model tests the efficacy of different samplng frames for a single artifact distribution. It might be interesting to be able to automatically iterate through a series of possible artifact distributions using the same sampling frame, and so test the efficacy of a single sampling frame on different types of artifact distributions.
## RELATED MODELS
The DIDI and DICI models (www.DigItTools.net) are also NetLogo models developed for survey experiments. This model is much simpler, and is aimed more at education than true statistical analysis of real survey strategies.
## CREDITS AND REFERENCES
This model was created by Isaac I.T. Ullah, PhD, 2022, at San Diego State University. It is intended for educational purposes only, and comes with no warantee or guarantee of accuracy. The model derives from an analog sampling experiment lab created as part of ANTH 302 "Principles of Archaeology," and is used in a presention I have given at the 2022 Society for American Archaeology meetings in Chicago. It is available under the GNU public license, and is published on the web at http://isaacullah.github.io/models/Sampling_Experiment.html. Please cite the author if you use this model in any publication.
(back to the NetLogo User Community Models)