documentation.conf

extensionName = "rnd"
markdownTemplate = """
# NetLogo `rnd` Extension

The `rnd` extension comes bundled with NetLogo 6.0 and later. You can find versions the latest version of `rnd` as well as archives of releases compatible with older NetLogo versions [in the project's Github releases page here](https://github.com/NetLogo/Rnd-Extension/releases). Just unzip the file under NetLogo's `extensions/` folder.

{{> USING.md}}

## Primitives

{{#contents}}{{#prims}}
[`{{name}}`](#{{primitive.extensionName}}{{primitive.name}})
{{/prims}}{{/contents}}

{{#primitives}}
{{> primTemplate}}

***

{{/primitives}}

{{> BUILDING.md}}
{{> LICENSE.md}}
"""

primTemplate = """
#### `{{name}}`

{{#examples}}
> <tt>{{primitive.fullName}}{{#args}} <i>{{name}}</i>{{/args}}</tt>
{{/examples}}

{{{description}}}
"""

filesToIncludeInManual = [ "USING.md", "primitives" ]

tableOfContents = {
  "agentset": "AgentSet Primitives",
  "list"    : "List Primitives"
}

primitives = [
  {
    name: weighted-one-of,
    type: reporter,
    returns: agent,
    tags: ["agentset"],
    arguments: [ { type: agentset }, { name: reporter, type: "reporter block" } ],
    description: """
Reports a random agent from <tt><i>agentset</i></tt>.

The probability of each agent being picked is proportional to the weight given by the <tt><i>reporter</i></tt> for that agent. The weights must not be negative.

If the agentset is empty, it reports [`nobody`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#nobody).

Here is a full rewrite of the **Lottery Example** model using the `rnd:weighted-one-of` primitive:

```
extensions [ rnd ]

to setup
  clear-all
  ; create a turtle on every fifth patch
  ask patches with [ pxcor mod 5 = 0 and pycor mod 5 = 0 ] [
    sprout 1 [
      set size 2 + random 6 ; vary the size of the turtles
      set label 0           ; start them out with no wins
      set color color - 2   ; make turtles darker so the labels stand out
    ]
  ]
  reset-ticks
end

to go
  ask rnd:weighted-one-of turtles [ size ] [
    set label label + 1
  ]
  tick
end
```
"""
  },
  {
    name: weighted-n-of,
    type: reporter,
    returns: agentset,
    tags: [ "agentset" ],
    arguments: [ { name: size, type: number }, { type: agentset }, { name: "[ reporter ]", type: "reporter block" } ],
    description: """
Reports an agentset of the given <tt><i>size</i></tt> randomly chosen from the <tt><i>agentset</i></tt>, with no repeats.

The probability of each agent being picked is proportional to the weight given by the <tt><i>reporter</i></tt> for that agent. The weights must be non-negative numbers.

It is an error for <tt><i>size</i></tt> to be greater than the size of the <tt><i>agentset</i></tt>.

If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.
"""
  },
  {
    name: weighted-n-of-with-repeats,
    type: reporter,
    returns: "list",
    tags: [ "agentset" ],
    arguments: [ { name: size, type: number }, { type: agentset } , { name: "[ reporter ]", type: "reporter block" } ],
    description: """
Reports a **list** of the given <tt><i>size</i></tt> randomly chosen from the <tt><i>agentset</i></tt>, with repeats. (Why a list instead of an agentset? Because an agentset cannot contain the same agent more than once.)

The probability of each agent being picked is proportional to the weight given by the <tt><i>reporter</i></tt> for that agent. The weights must be non-negative numbers.

It is **not** an error for <tt><i>size</i></tt> to be greater than the size of the <tt><i>agentset</i></tt>, but there has to be at least one candidate.

If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.

If all weights are `0.0`, each candidate has an equal probability of being picked.
"""
  },
  {
    name: weighted-one-of-list,
    type: reporter,
    returns: anything,
    tags: [ "list" ],
    arguments: [ { type: list }, { name: anonymous-reporter, type: reporter } ],
    description: """
Reports a random item from <tt><i>list</i></tt>.

The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)

It is an error for the list to be empty.

A common way to use the primitive is to have a list of lists, where the first item of each sublist is the thing you want to choose and the second item is the weight. Here is a short example:

```
let pairs [ [ "A" 0.2 ] [ "B" 0.8 ] ]
repeat 25 [
  ; report the first item of the pair selected using
  ; the second item (i.e., `last p`) as the weight
  type first rnd:weighted-one-of-list pairs [ [p] -> last p ]
]
```

This should print `B` roughly four times more often than it prints `A`.

If you happen to have your items and your weights in two separate lists, you can combine them into pairs by using a combination of [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map) and [`list`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#list):

```
let items [ "A" "B" "C" ]
let weights [ 0.1 0.2 0.7 ]
let pairs (map list items weights)
```

Since we apply [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map) to both the `items` list and the `weights` list, the parentheses are needed in `(map list items weights)`. We also use the concise anonymous procedure syntax (see the [programming guide](http://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures)) to pass [`list`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#list) as the reporter for [`map`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#map). The same thing could have been written `(map [ [a b] -> list a b ] items weights)`.
"""
  },
  {
    name: weighted-n-of-list,
    type: reporter,
    returns: list,
    tags: [ "list" ]
    arguments: [ { name: size, type: number }, { type: list }, { name: anonymous-reporter, type: reporter } ],
    description: """
Reports a list of the given <tt><i>size</i></tt> randomly chosen from the <tt><i>list</i></tt> of candidates, with no repeats.

The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)

It is an error for <tt><i>size</i></tt> to be greater than the size of the <tt><i>list</i> of candidates</tt>.

If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.

The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#shuffle) on the result).

Example:
```
let candidates n-values 8 [ [n] -> 2 ^ (n + 1) ] ; make a list with the powers of two
print rnd:weighted-n-of-list 4 candidates [ [w] -> w ]
```

This should print a list of four numbers, where the bigger numbers (32, 64, 128, 256) have a much better chance to show up than the smaller ones (2, 4, 8, 16).
"""
  },
  {
    name: weighted-n-of-list-with-repeats,
    type: reporter,
    returns: list,
    tags: [ "list" ],
    arguments: [ { name: size, type: number }, { type: list }, { name: anonymous-reporter, type: reporter } ],
    description: """
Reports a list of the given <tt><i>size</i></tt> randomly chosen from the <tt><i>list</i></tt> of candidates, with repeats.

The probability of each item being picked is proportional to the weight given by the <tt><i>anonymous-reporter</i></tt> for that item. The weights must not be negative. The first argument passed to the anonymous procedure refers to the list item. (See the [Anonymous Procedures section](https://ccl.northwestern.edu/netlogo/docs/programming.html#anonymous-procedures) of the Programming Guide for more details.)

It is **not** an error for <tt><i>size</i></tt> to be greater than the size of the <tt><i>list</i></tt> of candidates, but there has to be at least one candidate.

If, at some point during the selection, there remains only candidates with a weight of `0.0`, they all have an equal probability of getting picked.

If all weights are `0.0`, each candidate has an equal probability of being picked.

The items in the resulting list appear in the same order that they appeared in the list of candidates. (If you want them in random order, use [`shuffle`](http://ccl.northwestern.edu/netlogo/docs/dictionary.html#shuffle) on the result).

Example:
```
let pairs [ [ "A" 0.2 ] [ "B" 0.8 ] ]
print map first rnd:weighted-n-of-list-with-repeats 25 pairs [ [p] -> last p ]
```

This should print a list of 25 `A`s and `B`s, with roughly four times as many `B`s than `A`s.
"""
  }
]