In jonathan-g/analyzeBehaviorspace: Processes NetLogo BehaviorSpace Output

knitr::opts_chunk$set(
  collapse = TRUE,
  echo=FALSE,
  comment = "#>"
)

library(analyzeBehaviorspace)

Introduction

Getting Started

Install NetLogo

First, download and install NetLogo from https://ccl.northwestern.edu/netlogo/download.shtml. NetLogo is available for Windows, MacOS, and Linux. Follow the installation instructions for your operating system on the Download page.

Running a BehaviorSpace Experiment

The analyzeBehaviorspace package analyzes output from a NetLogo BehaviorSpace experiment, so to use this package we first need to create a BehaviorSpace experiment in NetLogo and run it.

Start NetLogo, open the File menu, and select Models Library. This should open a window for selecting a model. You should see a list of model topics under the heading Sample Models. If you don't, click on Sample Models to expand the topic list. Click on Social Science and then click on Segregation to open the housing segregation model.

The segregation model is a famous model created by Thomas Schelling in the late 1960s to study housing segregation. You can read more about it in Schelling's book, Micromotives and Macrobehavior, but here we're just going to use it to examine the way that varying two parameters affects the stability of the model.

In this model, there are 2601 squares and the model is set up with roughly equal numbers of orange and blue turtles occupying a certain percentage of those squares (this percentage is represented by the variable density).

Turtles are labeled happy or unhappy depending on the fraction of the turtles on neighboring patches that are the same color as they are. Each turtle looks at the turtles on neighboring patches and calculates the percentage of these that are the same color as itself. If this percentage is greater or equal to the variable %-similar-wanted the turtle is happy and if the percentage is less, then it is unhappy.

At each tick, all happy turtles stay where they are and each of the unhappy ones moves to a random vacant patch. The model keeps track of the number of happy and unhappy turtles, as well as the average percentage of same-color neighbors across all of the turtles. The model and keeps running until there are no unhappy turtles.

For the BehaviorSpace experiment, we will vary the two variables density and %-similar-wanted and monitor the average fraction of similar neighbors and the percentage of turtles that are unhappy.

In order to keep the run time under control, we will limit the model to run for no more than 200 ticks.

Open BehaviorSpace by clicking on the Tools menu and selecting BehaviorSpace. Then click on the New button to create a new BehaviorSpace experiment. Fill in the experiment following the picture below:

This experiment will vary density from 80% to 95% in steps of 5% and vary %-similar-wanted from 25% to 95% in steps of 2%. It will run the model 10 times for each configuration.

Measuring at every step of the model runs will create enormous data files and for this example, we only want to know how long it takes the model to finish running, so un-check Measure runs at every step in order to only record the model output values for the end of the run.

This experiment will run the model until it either stops on its own or reaches 200 ticks. At the last tick (when the model stops), it will record the values of two of the model's reporters: percent-similar and percent-unhappy.

Click on the OK button to save the experiment and then click Run to run it. You will need to configure the run to generate the required output:

Check Table output, uncheck Update view and Update plots and monitors. Experiments run much faster if they don't have to update the model displays. Under Simultaneous runs in parallel NetLogo will make a good guess, based on your computer's hardware and it's best to accept this default value.

Now click on the OK button. BehaviorSpace will ask you to give it a filename for saving your experiment's results (the default will be Segregation experiment-table.csv). Give it a file name and then let the experiment run (this may take some time).

Now you're ready to run analyzeBehaviorspace.

Running analyzeBehaviorspace

In an R session, load the analyzeBehaviorspace library and launch an analyzeBehaviorspace shiny application:

library(analyzeBehaviorspace)

launch_abs()

When the application launches, it will open a web browser window where you can load your data file and analyze the data.

Under Choose csv file, click the Browse... button and choose the file you saved from BehaviorSpace (by default, this is Segregation experiment-table.csv). After the file finishes loading, you should see something like this:

There is a table at the bottom right with the outputs from the experimental run. You are now ready to start graphing the results. Using the selectors for the plot, choose percent-similar-wanted for the x-axis, and tick for the y-axis. Check both points and lines. You will see the number of ticks the model took to make all the turtles happy, or 200 ticks for runs when the model ran out of time. The values indicated by the dots are the average for the 10 model runs at each value of percent-similar-wanted (in the original model, the variable was called %-similar-wanted, but analyzeBehaviorspace translates many common symbols to words).

This shows us that for percent-similar-wanted less than about 50%, the model converges quickly to a state where every turtle is happy, and that the time it takes to converge does not change very much as percent-similar-wanted increases. Above 50%, increasing percent-similar-wanted causes large increases in the time to converge until around 77%, where the model does not converge by 200 ticks.

Suppose we want to get a sense of the amount of variation from one model run to another for each value of percent-similar-wanted? We can tick error bars or bands under the Std. Dev. options. This will display either error bars around the points or bands above and below the lines, indicating one standard deviation above and below the average values.

We see that there is very little variation from run to run below 50% and above 75%, but that between 50% and 75%, there is a lot of run-to-run variation. A lot of this variation happens because for each value of percent-similar-wanted, we varied density from 80% to 95%. We can display each value of density separately if we use the Group by option to select density. This will display the model output for each value of density in a different color:

Now we can see that the value of percent-similar-wanted at which the time to converge begins to rise and the value at which the model reaches 200 ticks without converging both depend strongly on the density of occupied patches. The greater the density, the lower the value of percent-similar-wanted at which it becomes difficult to satisfy all the turtles.

We also see that the range of values for percent-similar-wanted for which there is considerable variation from run to run is much smaller when we consider each value of density separately.

Renaming variables

If you want your plot to look prettier, you can rename variables in your data and the plot will reflect the new names: Scroll down to Rename variables, select percent-similar-wanted, type % similar wanted in the to box, and click on the Rename button. Next, select tick, type Time to converge in to and click Rename. The graph will now look like this:

Saving Output

If you want to save the results of your analysis, either as images of the graphs or as tables of numbers that you can read into Excel, R, or another program for further analysis, you can scroll down to the Save Plot and Save Table buttons on the left. Save Plot will save the current plot as a .png image file. Save Table will save the table of data as a .csv file.

If you check Summary table, then the table you save will correspond to the data plotted in the figure (with averages and standard deviations for the y-axis variable at each value of the x-axis and grouping variables). If Summary table is not checked, then you will save a .csv file with the values of all the variables. In either case, the table displayed in the lower right of the screen shows the data that will be saved.

jonathan-g/analyzeBehaviorspace documentation built on July 23, 2022, 11:01 a.m.