NetLogo User Community Models

(back to the NetLogo User Community Models)

Download If clicking does not initiate a download, try right clicking or control clicking and choosing "Save" or "Download". Try It in NetLogo Web

## What is it?

Choice of a mate can impact ultimate fitness of individual organisms and the evolution of species. This model explores the decision-making process of female frogs engaged in the task of choosing a male mate. Two classic theories for female decision-making in this task—the _best-of-n_ and the _minimum-threshold_ theories—are compared (along with the availability of a "null" model consisting of random choice).

## How it works

The model includes male and female treefrog agents engaged in the mate choice task. The world is a two-dimensional "swamp" with realistic dimensions of 10 m by 25 m.

Female agents seek male mates according to their mate choice strategy—the _best-of-n_, the _minimum-threshold_, or the random strategy. The first two strategies also include a strategy parameter, to specify the _N_ in the _best-of-n_ strategy or the threshold in the _minimum-threshold_ strategy. Female agents are initially randomly distributed (according to a continuous uniform probability distribution) around the edges of the swamp.

Male agents advertise their quality (via the pulse number of their advertisement calls) and their location. Males are distributed on non-overlapping territories at initialization, from which they advertise but do not move (unless they mate). The spatial distributions available are Gaussian (males more clustered in the center of the swamp), inverse Gaussian (more males on the edges, as might occur around the edges of a pond), and random (a continuous uniform probability distribution over the area of the swamp).

The model proceeds with female agents sampling the male agents, selecting a target male (according to her own strategy), and approaching him. Females using the _best-of-n_ strategy resample at each time step but females using the other strategies resample only if their initial target male is removed by mating. When females are within the pre-determined mating distance of a male, the pair mates and is removed from the simulation.

## How to use it

### Setup parameters

Adjust the following controls before pressing the **Setup** button to initialize the model.

#### Female frog parameters

* **num-females**

The number of female frogs created when the model is initialized.

* **female-strategy**

The mate sensing/targeting strategy employed by the female frogs.

* _best-of-n_

At each step, the female frog senses the closest _N_ (set with the **best-of-n** slider) available (unmated) male frogs, and targets the one with the highest pulse number. Note that as the female moves toward the targeted male, the set of the _N_ closest available males sensed by the female may change, which can result in the female targeting a different male even if her previously selected target is still available.

* _min-threshold_

The female frog senses the available males with a pulse number greater than or equal to the value of the **min-threshold** parameter, and targets the nearest of those males. If another female reaches the targeted male first, then another male is targeted, using the same strategy.

* _uniform-random_

The female frog senses all available males in the swamp, and selects one at random, where each male has a uniform likelihood of selection. If another female reaches the targeted male first, then another male is targeted, using the same strategy.

* **best-of-n**

The control parameter (number of nearby male frogs sensed) for the _best-of-n_ mating strategy.

* **min-threshold**

The control parameter (minimum pulse number threshold) for the _min-threshold_ mating strategy.

* **phonotaxis-speed**

The distance traveled (in cm) each second by a female frog toward the currently targeted male.

* **random-walk-speed**

The distance traveled (in cm) each second, in a random direction, by a female frog that does not currently have a male targeted.

#### Male frog parameters

* **num-males**

The number of male frogs created when the model is initialized.

* **male-territory-radius**

Radius of circular territory occupied by each male. No male's territory is allowed by the model to overlap with another male's territory, nor is any male's territory allowed to extend beyond the edges of the swamp.

* **male-distribution**

The distribution of male frogs on initialization. (Placement is always subject to the territorial radius constraint, as described above: any trial placement which violates the non-overlapping rule results in a resampling/re-placement of the male frog.)

* _uniform-random_

Male frogs are placed by sampling from a 2-dimensional continuous uniform probability distribution.

* _gaussian_

Male frogs are placed by sampling from a 2-dimensional Gaussian distribution, with the expected value located at the center of the swamp. This produces a higher concentration of males in the center of the swamp.

* _inverse-gaussian_

Male frogs are placed by sampling from a 2-dimensional Gaussian distribution, where the 4 quadrants of the distribution are translated to the 4 corners of the swamp, resulting in a higher concentration of males in the corners and along the edges.

* **mean-pulse-number**

Mean of the Gaussian distribution from which male pulse numbers are sampled.

* **stdev-pulse-number**

Standard deviation of the Gaussian distribution from which male pulse numbers are sampled.

* **mating-radius**

Distance between the centers of male and female frog agents within which mating occurs. (In general, this should be set to the distance between centers at which 2 frog bodies would be in contact.)

### General simulation controls

* **max-run-length**

Maximum length (in simulated seconds) of a simulation run. Note that a simulation may end before this time has elapsed, if no more mating is possible—if all males and/or all females have mated. Also, note that this value can be changed while a simulation is in progress, and it will take effect immediately.

* **Setup**

Initialize the simulation model, using the parameter values set in the selectors and sliders described in **Setup parameters** (above). Note that changing those controls has no effect on the simulation until the *Setup* button is pressed.

When not running in NetLogo Web, pressing **Setup** also gives the user the option to import global and agent variable values from a file; any values so imported will override values specified in the user interface. (See **File format for importing global and agent variable values**, below, for more information on this feature.)


If the "No" option is selected, no data will be imported in the current run. If the "Skip for this session" option is selected, this prompt will not be displayed for any subsequent runs, until the model is closed and re-opened.

* **Go**

Run a simulation using the initialized model.

## Things to notice when using the model

### General display

When the model is initialized, and as it is running, unmated male frogs are colored yellow, unmated female frogs are green, and mated pairs are colored red. In the plots listed below, the same colors (yellow, green, and red) are used for the respective groups (unmated males, unmated females, and mated frogs).

### Monitors and plots

The following are updated continuously as the model runs.

* **Mated Pairs** (monitor)

Displays the number of male/female pairs that have mated so far in the current run.

* **Time to Mate** (plot and monitor)

Displays a histogram and average of elapsed simulated time (in minutes) between the model start and the time of mating, for all mated pairs.

* **Pulse Numbers** (plot and monitors)

Displays 2 (overlayed) histograms, along with average values, of pulse numbers for all males (plotted in yellow) and mated males (in red).

* **Distance Traveled** (plot and monitors)

Displays 2 (overlayed) histograms, along with average values, of total distance traveled (in cm) for all females (plotted in green) and mated females (in red).

* **Mates Targeted** (plot and monitors)

Displays 2 (overlayed) histograms, along with average values, of males targeted by all females (plotted in green) and mated females (in red). Note that in the _best-of-n_ mating strategy, a female may end up targeting the same male more than once. These will be counted as separately targeted males in the plotted histograms and computed averages.

## Things to try

1. Systematic changes in the number of males and females on setup can dramatically change the sex ratio. Explore cases where males are rare versus those where females are rare. How does this influence the quality of mates that frogs find?

2. The choice of N (for the _best-of-n_ strategy) or the threshold (for the _minimum-threshold_ strategy) can create populations of females with very high standards. Does this always result in females acquiring the “best” mates? How do these choices interact with the mean quality of the available males?

3. One might hypothesize that a larger territory would be better for males. Change the territory radius and observe the final mate quality. Do larger or smaller territory sizes maximize the average pulse number of mated males? Does this depend on male and female densities or the sex ratio?

4. Female frogs provide tasty morsels for many predators. The smaller the distance females travel, the less time they spend exposed to predators. What combinations of conditions minimize distance traveled by females?

## File format for importing global and agent variable values

In order to import global and agent variable values, the source file must contain the variable names and values in a specific format. The format is basically a "multi-section CSV" format: there are multiple comma-separated CSV sections, and each section is preceded by a section identifier, indicating whether the subsequent lines should be applied to global variables, female agent variables, or male agent variables. One or more sections may be omitted from the file; no overriding of the values set in the UI for such sections will be performed. When imported values override values set in **Interface** controls, the values indicated by those controls will be changed to match the overriding values.

Note that the section names are case-sensitive, and must be enclosed in square brackets.

#### `[globals]`

If present, this section should include 2 lines of CSV data. The first line contains 1 or more global variable names, separated by commas. (Each variable name may optionally be enclosed in quotes.) The second line contains the values for the variables specified in the first line, in the same order; again, these values must be separated by commas, and string values may be enclosed in quotes.

The following variable names are recognized in this section. (For those variables corresponding to controls by the same names in **Interface**, details may be found in the descriptions of those controls, above.)

* `seed`

Random number generator seed value. (The default seed is generated automatically from the system clock.)

* `max-run-length`

* `num-females`

* `female-strategy`

* `best-of-n`

* `min-threshold`

* `phonotaxis-speed`

* `random-walk-speed`

* `num-males`

* `male-territory-radius`

* `male-distribution`

* `gaussian-sigma-x`

Standard deviation of Gaussian distribution used to generate the male frogs' _X_ positions when **male-distribution** is set to "gaussian" or "inverse-gaussian".

* `gaussian-sigma-y`

Standard deviation of Gaussian distribution used for generating the male frogs' _Y_ position when **male-distribution** is set to "gaussian" or "inverse-gaussian".

* `mean-pulse-number`

* `stdev-pulse-number`

* `round-pulse-numbers?`

* `round-to-half?`

If the value of `round-pulse-numbers?` (which is `false` by default) is overridden with a value of `true`, randomly generated male frog agent pulse numbers will be rounded. If `round-to-half?` is `false` (the default value), rounding will be to the nearest integer; otherwise, rounding is to the nearest value of the form _k_ + 0.5, where _k_ is an integer.

* `mating-radius`

#### `[females]`

This section should contain 2 or more lines of CSV data. The first line contains 1 or more female agent variable names, optionally enclosed in quotes and separated by commas. Subsequent lines specify values corresponding to the names in the first line; these values override agent-specific variable values, 1 line per agent. If there are fewer value lines than female frog agents, some of the agents will keep the values originally assigned; if there are more value lines than female frog agents, excess value lines are ignored.

The following variable names are recognized in this section. Note that most of these are taken from population-wide **Interface** controls (with slightly different names); overriding these can be used to configure the agents with heterogeneous, rather than homogenous, values for these variables.

* `xcor`

Starting _X_ position of agent, in the interval [-0.5 24.5), overriding the randomly generated value.

* `ycor`

Starting _Y_ position of agent, in the interval [-0.5 9.5), overriding the randomly generated value.

* `strategy`

Overrides the value assigned from the **female-strategy** selector.

* `strategy-parameter`

Overrides the value assigned from either the **best-of-n** slider or the **min-threshold** slider, depending on the value of **female-strategy**. If the latter is overridden, whether globally or individually (by specifying a value for `strategy`), this variable should be assigned a value as well.

* `speed-phonotaxis`

Overrides the value assigned from the **phonotaxis-speed** slider.

* `speed-random`

Overrides the value assigned from the **random-walk-speed** slider.

#### `[males]`

This section should contain 2 or more lines of CSV data. The first line contains 1 or more male agent variable names, optionally enclosed in quotes and separated by commas. Subsequent lines specify values corresponding to the names in the first line; these values override agent-specific variable values, 1 line per agent. If there are fewer value lines than male frog agents, some of the agents will keep the values originally assigned; if there are more value lines than male frog agents, excess value lines are ignored.

The following variable names are recognized in this section. Note that some of these are taken from population-wide **Interface** controls (with slightly different names); overriding these can be used to configure the agents with heterogeneous, rather than homogenous, values for these variables.

* `xcor`

Starting _X_ position of the agent, in the interval [-0.5 24.5), overriding the randomly generated value.

* `ycor`

Starting _Y_ position of the agent, in the interval [-0.5 9.5), overriding the randomly generated value.

* `pulse-number`

Overrides the value assigned randomly based on the **mean-pulse-number** and **stdev-pulse-number** controls.

* `territory-radius`

Radius of the agent's territory in meters. Unless overridden, this is taken as the value of the **male-territory-radius** slider, divided by 100.^[1]

* `mate-proximity`

Distance in meters within which the male frog agent can mate with an available female frog agent. Unless overridden, this is taken as the value of the **mating-radius** slider, divided by 100.^[1]

1. The units of distance employed in the UI are centimeters (cm); however, in the model code—and in the import files—distances are expressed in meters (m).

#### Comments

To include comments in an import file, simply place them before any section marker, or after a section marker that doesn't match one of the 3 listed above (`[globals]`, `[females]`, `[males]`).

#### Data import example

Assume we have a file named `sample-import.csv`, with these contents:

```ini
[globals]
seed,num-females,num-males,female-strategy,best-of-n,mean-pulse-number
13,14,20,best-of-n,5,15

[females]
xcor,ycor
2,-0.5
7,-0.5
12,-0.5
17,-0.5
22,-0.5
2,9.499999
7,9.499999
12,9.499999
17,9.499999
22,9.499999
-0.5,2
-0.5,7
24.499999,2
24.499999,7

[males]
pulse-number
10
11
12
13
14
15
16
17
18
19
20
```

After pressing **Setup** and importing `sample-import.csv`, we have this result:

<img src="images/sample-import.png" alt="Results of importing sample-import.csv" title="Results of importing sample-import.csv" width="1083" height="479" />

Note that the **num-females**, **num-males**, **female-strategy**, **best-of-n**, and **mean-pulse-number** controls in the **Interface** match the corresponding values in the `[globals]` section of `sample-import.csv`. Also, the female frogs are distributed at regular intervals around the edge of the swamp (with no apparent randomness), as specified in the `[females]` section. Finally, if we inspect the male frogs, we'll see that 11 of them have `pulse-number` values matching those in the `[males]` section, while the other 9 have randomly generated values.

## Running the model with BehaviorSpace

Currently, the model has a number of BehaviorSpace experiments pre-configured for use. These perform repeated trials across ranges of input parameter values, capturing the output to comma-separated values (CSV) files.

To view, edit, or run these experiments, select the **Tools/BehaviorSpace** menu command; a selection list of defined experiments will be displayed:


For information on creating and editing BehaviorSpace experiments, see [BehaviorSpace Guide](https://ccl.northwestern.edu/netlogo/docs/behaviorspace.html).

When an experiment is selected and the **Run** button pressed, the **Run options** window is displayed.


It is recommended to select the **Table output** checkbox option, but not the **Spreadsheet output** checkbox, and to leave the **Simultaneous runs in parallel** field set to the default value (which is taken from the detected number of processing cores on the computer).

After clicking the **OK** button in the **Run options** window, you'll be given a chance to select an output location and file name. (The default output file name is composed of the model name, experiment name, and output layout option.) After clicking **Save**, the BehaviorSpace experiment starts to run. While it's running, a status window is displayed:


In most cases, it's a good idea to un-check the **Update view** and **Update plots and monitors** checkboxes; otherwise, the BehaviorSpace trials will be slowed down as their progress is animated in the NetLogo view.

## Running the model on NetLogo Web

As currently implemented, some features described above&mdash;including BehaviorSpace, extensions, and file I/O (used by the data import feature)&mdash;are not supported in NetLogo Web.

As of May 11, 2022, a NetLogo Web version of this model can be accessed [here](https://netlogoweb.org/web?https://nick-bennett.github.io/mate-choice-model/netlogo/tree-frog-mate-choice-web.nlogo).

In general, in order to run in NetLogo Web, 1 line in the **Code** page of the full version of the model must be commented out, to prevent NetLogo Web from failing when attempting to load the extensions used by the data import feature. (It's always a good idea to save a working NetLogo model file under a new name, before making any changes to the **Code** or **Interface** pages.)

To prepare the model for use in NetLogo Web, change the first few lines of the **Code** page, from
```
;; Comment out the __includes line for NetLogo Web use.

__includes ["includes/behaviorspace-stats.nls" "includes/parameter-import.nls"]
```
to
```
;; Comment out the __includes line for NetLogo Web use.

; __includes ["includes/behaviorspace-stats.nls" "includes/parameter-import.nls"]
```
(Note the addition of a semicolon to the line that starts with `__includes`. This change turns the line into a comment, which NetLogo Web will not execute.)

For more information on using NetLogo Web, see the [NetLogo Web site](https://netlogoweb.org/).

## Modifying and extending the model

* Arguably, some of the more useful modifications to the model would include reducing the controls available in the **Interface** page, to simplify the user experience for those not expert in behavioral ecology. To that end, a number of comments are included in the `globals` section and the `setup-globals` procedure (both in the **Code** page), with basic instructions on the changes needed to allow removal of one or more of the controls in the **Interface** page. Please see those comments for more information.

* It would also be straightforward to extend the model in several other ways.

* Currently, the threshold is the same (according to input) for all females within a single simulation population. In the field, it is likely that individual females vary in their choosiness. One can extend the model by generating threshold values (for the _min-threshold_ strategy) according to a probability distribution.

This extension could be implemented by adding the necessary controls (or global variables) to set the parameters for a distribution of threshold values, and then referencing those parameters in the `setup-females` procedure, prior to the invocation of `override`.

* The current model includes “perfect” perception by females of male signals and a direct approach of females toward males. The real world includes errors in perception and execution by females. Models that incorporate such uncertainty would be valuable. One can thus extend the model by limiting the sensing and/or targeting accuracy of female frogs.

Extensions to the sensing, target selection, or movement logic&mdash;such as adding "fuzziness", "wiggling", or other types of less-than-perfect perception or movement&mdash;would generally require multiple changes to the UI and the code. First, additional controls or global variables would probably be needed, to parameterize the level of uncertainty; new agent variables might also be required (in the `females-own` block) to store agent-specific parameters. These added variables would then be referenced by modified code in the `best-of-n-pool`, `min-threshold-pool`, and `uniform-random-pool`, sensing procedures; the `select-best-of-n`, `select-min-threshold`, and `select-uniform-random` target selection procedures; and/or the `move-to-mate` procedure.

## Credits and references

1. The original model was developed in the SimWorld environment by Matthias Scheutz (Tufts University) and colleagues. Scheutz M, Harris J. An overview of the SimWorld agent-based grid experimentation system. In: Werner DF, Kurowski K, Schott B, editors. Large-Scale Computing Techniques for Complex System Simulations: Wiley; 2011. https://onlinelibrary.wiley.com/doi/10.1002/9781118130506.ch4 )

2. The model and initial research findings are described in: Ferreira GBS, Scheutz M, and Boyd SK (2018) Mate choice strategies in a spatially-explicit model environment. PLoS ONE 13(8): e0202680. https://doi.org/10.1371/journal.pone.0202680 .

3. Datasets from the original model implementation are available at Dryad: doi:10.5061/dryad.2350931 and the University of Notre Dame repository: doi:10.7274/R08S4N0S.

4. This model was implemented in NetLogo by Nicholas Bennett &amp; Sunny Boyd.

5. If you use or refer to this model in a publication, we ask that you cite the model itself, the source publication and the NetLogo software:

For the model itself:

* Boyd, S. and Bennett, N. (2018). NetLogo Treefrog Mating Model. (INSERT URL HERE). Department of Biological Sciences, University of Notre Dame, Notre Dame, IN. CNM Ingenuity, Central New Mexico Community College, Albuquerque, NM.

For the source publication:

* Ferreira GBS, Scheutz M, and Boyd SK (2018) Mate choice strategies in a spatially-explicit model environment. PLoS ONE 13(8): e0202680.

Please cite the NetLogo software as:

* Wilensky, U. (1999). NetLogo. http://ccl.northwestern.edu/netlogo/. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.

6. Copyright 2018 Nicholas Bennett, Sunny Boyd, and the University of Notre Dame

7. This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).

[](https://creativecommons.org/licenses/by-nc-sa/4.0/)

8. We gratefully acknowledge the support of the National Science Foundation (IOS # 0725187, 1257777, 1257815).

* v1.0.0, 2018-02-22, Nicholas Bennett:

* Initial project delivery.
* Validation checks.

* v1.0.1, 2018-02-25, Nicholas Bennett:

* Data importing.
* Expanded **Info** content.
* Use of include files.
* Creation of separate NetLogo Web version.

* v1.0.2, 2022-05-10, Sunny Boyd:

* Updated credits and license information.

* v1.0.3, 2022-05-11, Nicholas Bennett:

* Successive `if` statements replaced by multi-branch `if-else` statement (aka `if-else` ladder) in `setup-females` procedure.
* Clarification of some instructions in **Info** tab.
* CC BY-NC-SA image link in **Info** tab fixed.
* Credits & licenses in **Code** tab reformatted for readability.