Skip to contents

Add a flexible variable

Source: R/tidyabm_class.R
add_variable.Rd

A variable is expected to updated at various (if not all) iterations. It gets initiated at the start with the status quo of the model and is accessible throughout runtime. Compared to a characteristic, it thus requires runtime resources but is flexibly updated at every iteration.

Usage

add_variable(.tidyabm, ..., .overwrite = FALSE)

# S3 method for tidyabm
add_variable(.tidyabm, ..., .overwrite = FALSE)

Arguments

.tidyabm

a tidyabm object

...

<data-masking> Name-value pairs. The name gives the name of the variable. To avoid misunderstandings use unique variable names, also between agents and environments. Try to also avoid starting your name with a point/dot (.) because some internally added names use that pattern. Good variable names also do not have any whitespace and are all lowercase; use underscores to separate any words. It is recommended to also avoid the use of minus signs. Hence, a good variable name looks like this_is_a_great_name. The value has to be one of:

  • a single value (e.g., a character, numeric, logical, vector ...)

  • a function to be run at every iteration of the modelling process

Keep in mind that for single values that are not expected to change, set_characteristic is a better-fitting method as it is not re-run at every iteration of the modelling process.

For functions you may use a function which gets called at every iteration with two arguments, me (which is the tidyabm object at that specific point in time) and abm (which is the whole tidyabm object). Note that for tidyabm_env objects these two arguments are the same but for tidyabm_agent objects they are different in that the first (me) is the current agent and the second (abm) is the whole environment model. If you write your own functions or need to provide additional arguments to functions, use the style of anonymized functions directly in-line (through function(me, abm) ... or \(me, abm) ...).

.overwrite

if FALSE (the default), variables with the same name will not be overwritten (a warning will be issued)

Value

a tidyabm object

Examples

create_agent() %>%
  set_characteristic(age = 15) %>%
  add_variable(share_same_age = function(me, abm) {
                neighbors <- get_neighbors(me)
                return(sum(neighbors$age == me$age)/nrow(neighbors))
              }) %>%
  add_variable(feels_welcome = \(me, abm) share_same_age >= .50)
#> # A tibble: 1 × 1
#>     age
#> * <dbl>
#> 1    15
#> # ABM agent
#> * 1 agent characteristic(s), 
#> * 2 agent variable(s), 
#> * 0 agent rule(s), 

create_grid_environment(seed = 9896, size = 5) %>%
  add_variable(m_age = \(me, abm) mean(convert_agents_to_tibble(me)$age, na.rm = T))
#> # A tibble: 0 × 0
#> # ABM grid environment
#> * 5x5, 0 agents
#> * 0 environment characteristic(s), 
#> * 1 environment variable(s), 
#> * 0 environment rule(s), 
#> * not initiated