Distribute a given characteristic across a range of agents

This function allows you to set a characteristic for a set of agents that needs is initially dependent on each other (e.g., a normally distributed characteristic). If you just want to set an individual characteristic to agents, use set_characteristic instead as it is much faster.

Usage

distribute_characteristic_across_agents(
  .tidyabm,
  .name,
  .value,
  ...,
  .overwrite = FALSE,
  .suppress_warnings = FALSE
)

# S3 method for tidyabm_env
distribute_characteristic_across_agents(
  .tidyabm,
  .name,
  .value,
  ...,
  .overwrite = FALSE,
  .suppress_warnings = FALSE
)

Arguments

.tidyabm

the tidyabm_env holding the (range of) agents

.name

character string representing the name of the new characteristic

.value

a vector of the same length as the range of agents or a single value (to apply to all) or a (anonymous) function to be called for each agent. For functions you may use a function which gets called for every agent with three arguments: i (a numeric iterator ranging from 1 for the first agent to n for the last agent), agent (the respective tidyabm agent), and agents (a tibble resembling all filtered agents before distribution of this characteristic started but after filter expressions were applied, see ...). The function should only return one value of the characteristic, namely the one for the current/respective agent. 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(i, agent, agents) ... or \(i, agent, agents) ...).

...

<data-masking> expressions that return a logical value and are defined in terms of all characteristics and variables of all added agents. This is to specify which agents get the new characteristic. If omitted, all present agents are receiving the new characteristic. If multiple expressions are included, they are combined with the & operator.

.overwrite

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

.suppress_warnings

if TRUE, .overwrite will not yield any warnings; default is FALSE, though

Value

tidyabm object

Examples

create_grid_environment(seed = 168, size = 20) %>%
  add_agents(create_agent(), 160) %>%
  distribute_characteristic_across_agents(
    'friend',
    \(i, agent, agents) ifelse(stats::runif(1) > 0.5, i-1, 0)
  )
#> # A tibble: 0 × 0
#> # ABM grid environment
#> * 20x20, 160 agents
#> * 0 environment characteristic(s), 
#> * 0 environment variable(s), 
#> * 0 environment rule(s), 
#> * not initiated

a1 <- create_agent() %>%
  set_characteristic(age = 'young')
a2 <- create_agent() %>%
  set_characteristic(age = 'old')
m <- create_grid_environment(seed = 486, size = 50) %>%
  add_agents(a1, 100) %>%
  add_agents(a2, 100) %>%
  distribute_characteristic_across_agents(
    'opinion',
    stats::rnorm(100),
    age == 'old'
  )