Package 'individual'

Description

Simulate a process where individuals in a given from state advance to the to state each time step with probability rate.

Usage

bernoulli_process(variable, from, to, rate)

Arguments

Value

a function which can be passed as a process to simulation_loop.

Description

This is a data structure that compactly stores the presence of integers in some finite set (max_size), and can efficiently perform set operations (union, intersection, complement, symmetric difference, set difference). WARNING: All operations are in-place so please use $copy if you would like to perform an operation without destroying your current bitset.

This class is defined as a named list for performance reasons, but for most intents and purposes it behaves just like an R6 class.

Methods

Method new()

create a bitset.

Usage

Bitset$new(size, from)

Arguments

size

the size of the bitset.

from

pointer to an existing IterableBitset to use; if NULL make empty bitset, otherwise copy existing bitset.

Method insert()

insert into the bitset.

Usage

b$insert(v)

Arguments

v

an integer vector of elements to insert.

Method remove()

remove from the bitset.

Usage

b$remove(v)

Arguments

v

an integer vector of elements (not indices) to remove.

Method clear()

clear the bitset.

Usage

b$clear()

Method size()

get the number of elements in the set.

Usage

b$size()

Method or()

to "bitwise or" or union two bitsets.

Usage

b$or(other)

Arguments

other

the other bitset.

Method and()

to "bitwise and" or intersect two bitsets.

Usage

b$and(other)

Arguments

other

the other bitset.

Method not()

to "bitwise not" or complement a bitset.

Usage

b$not(inplace)

Arguments

inplace

whether to overwrite the current bitset, default = TRUE

Method xor()

to "bitwise xor" get the symmetric difference of two bitset (keep elements in either bitset but not in their intersection).

Usage

b$xor(other)

Arguments

other

the other bitset.

Method set_difference()

Take the set difference of this bitset with another (keep elements of this bitset which are not in other)

Usage

b$set_difference(other)

Arguments

other

the other bitset.

Method sample()

sample a bitset.

Usage

b$sample(rate)

Arguments

rate

the success probability for keeping each element, can be a single value for all elements or a vector of unique probabilities for keeping each element.

Method choose()

choose k random items in the bitset.

Usage

b$choose(k)

Arguments

k

the number of items in the bitset to keep. The selection of these k items from N total items in the bitset is random, and k should be chosen such that $0 \le k \le N$.

Method copy()

returns a copy of the bitset.

In cases where a destination bitset already exists, it may be more performant to use the copy_from method instead.

Usage

b$copy()

Method copy_from()

overwrite the value of the bitset from another bitset.

This is similar to calling other$copy(), but can be more efficient by reusing the resources of the existing bitset.

Usage

b$copy_from(other)

Arguments

other

the other bitset.

Method to_vector()

return an integer vector of the elements stored in this bitset.

Usage

b$to_vector()

Description

This non-modifying function returns the number of intersecting elements between two bitsets a and b. This should be faster than writing a$copy()$and(b)$size() as it avoids the memory allocations of $copy().

Usage

bitset_count_and(a, b)

Arguments

Description

Renders the number of individuals in each category.

Usage

categorical_count_renderer_process(renderer, variable, categories)

Arguments

Value

a function which can be passed as a process to simulation_loop.

Description

Represents a categorical variable for an individual. This class should be used for discrete variables taking values in a finite set, such as infection, health, or behavioral state. It should be used in preference to IntegerVariable if possible because certain operations will be faster.

Methods

Public methods

• CategoricalVariable$new()

• CategoricalVariable$get_index_of()

• CategoricalVariable$get_size_of()

• CategoricalVariable$get_categories()

• CategoricalVariable$get_values()

• CategoricalVariable$queue_update()

• CategoricalVariable$queue_extend()

• CategoricalVariable$queue_shrink()

• CategoricalVariable$size()

• CategoricalVariable$.update()

• CategoricalVariable$.resize()

• CategoricalVariable$save_state()

• CategoricalVariable$restore_state()

• CategoricalVariable$clone()

Method new()

Create a new CategoricalVariable

Usage

CategoricalVariable$new(categories, initial_values)

Arguments

Method get_index_of()

return a Bitset for individuals with the given values

Usage

CategoricalVariable$get_index_of(values)

Arguments

Method get_size_of()

return the number of individuals with the given values

Usage

CategoricalVariable$get_size_of(values)

Arguments

Method get_categories()

return a character vector of possible values. Note that the order of the returned vector may not be the same order that was given when the variable was intitialized, due to the underlying unordered storage type.

Usage

CategoricalVariable$get_categories()

Method get_values()

return the value of the variable for the given individuals

Usage

CategoricalVariable$get_values(index = NULL)

Arguments

Method queue_update()

queue an update for this variable

Usage

CategoricalVariable$queue_update(value, index)

Arguments

Method queue_extend()

extend the variable with new values

Usage

CategoricalVariable$queue_extend(values)

Arguments

Method queue_shrink()

shrink the variable

Usage

CategoricalVariable$queue_shrink(index)

Arguments

Method size()

get the size of the variable

Usage

CategoricalVariable$size()

Method .update()

Usage

CategoricalVariable$.update()

Method .resize()

Usage

CategoricalVariable$.resize()

Method save_state()

save the state of the variable

Usage

CategoricalVariable$save_state()

Method restore_state()

restore the variable from a previously saved state.

Usage

CategoricalVariable$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CategoricalVariable$clone(deep = FALSE)

Arguments

Description

Represents a continuous variable for an individual.

Methods

Public methods

• DoubleVariable$new()

• DoubleVariable$get_values()

• DoubleVariable$get_index_of()

• DoubleVariable$get_size_of()

• DoubleVariable$queue_update()

• DoubleVariable$queue_extend()

• DoubleVariable$queue_shrink()

• DoubleVariable$size()

• DoubleVariable$.update()

• DoubleVariable$.resize()

• DoubleVariable$save_state()

• DoubleVariable$restore_state()

• DoubleVariable$clone()

Method new()

Create a new DoubleVariable.

Usage

DoubleVariable$new(initial_values)

Arguments

Method get_values()

get the variable values.

Usage

DoubleVariable$get_values(index = NULL)

Arguments

Method get_index_of()

return a Bitset giving individuals whose value lies in an interval $[a,b]$.

Usage

DoubleVariable$get_index_of(a, b)

Arguments

Method get_size_of()

return the number of individuals whose value lies in an interval Count individuals whose value lies in an interval $[a,b]$.

Usage

DoubleVariable$get_size_of(a, b)

Arguments

Method queue_update()

Queue an update for a variable. There are 4 types of variable update:

1. Subset update: The argument index represents a subset of the variable to update. The argument values should be a vector whose length matches the size of index, which represents the new values for that subset.

2. Subset fill: The argument index represents a subset of the variable to update. The argument values should be a single number, which fills the specified subset.

3. Variable reset: The index vector is set to NULL and the argument values replaces all of the current values in the simulation. values should be a vector whose length should match the size of the population, which fills all the variable values in the population

4. Variable fill: The index vector is set to NULL and the argument values should be a single number, which fills all of the variable values in the population.

Usage

DoubleVariable$queue_update(values, index = NULL)

Arguments

Method queue_extend()

extend the variable with new values

Usage

DoubleVariable$queue_extend(values)

Arguments

Method queue_shrink()

shrink the variable

Usage

DoubleVariable$queue_shrink(index)

Arguments

Method size()

get the size of the variable

Usage

DoubleVariable$size()

Method .update()

Usage

DoubleVariable$.update()

Method .resize()

Usage

DoubleVariable$.resize()

Method save_state()

save the state of the variable

Usage

DoubleVariable$save_state()

Method restore_state()

restore the variable from a previously saved state.

Usage

DoubleVariable$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

DoubleVariable$clone(deep = FALSE)

Arguments

Description

Describes a general event in the simulation.

Super class

individual::EventBase -> Event

Methods

Public methods

• Event$new()

• Event$schedule()

• Event$clear_schedule()

• Event$.process_listener()

• Event$.process_listener_cpp()

• Event$.resize()

• Event$save_state()

• Event$restore_state()

• Event$clone()

Method new()

Initialise an Event.

Usage

Event$new(restore = TRUE)

Arguments

Method schedule()

Schedule this event to occur in the future.

Usage

Event$schedule(delay)

Arguments

Method clear_schedule()

Stop a future event from triggering.

Usage

Event$clear_schedule()

Method .process_listener()

Usage

Event$.process_listener(listener)

Method .process_listener_cpp()

Usage

Event$.process_listener_cpp(listener)

Method .resize()

Usage

Event$.resize()

Method save_state()

save the state of the event

Usage

Event$save_state()

Method restore_state()

restore the event from a previously saved state. If the event was constructed with restore = FALSE, the state argument is ignored.

Usage

Event$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Event$clone(deep = FALSE)

Arguments

Description

Common functionality shared between simple and targeted events.

Methods

Public methods

• EventBase$add_listener()

• EventBase$.timestep()

• EventBase$.tick()

• EventBase$.process()

• EventBase$clone()

Method add_listener()

Add an event listener.

Usage

EventBase$add_listener(listener)

Arguments

Method .timestep()

Usage

EventBase$.timestep()

Method .tick()

Usage

EventBase$.tick()

Method .process()

Usage

EventBase$.process()

Method clone()

The objects of this class are cloneable with this method.

Usage

EventBase$clone(deep = FALSE)

Arguments

Description

This non-modifying function returns a new Bitset object of the same maximum size as the original but which only contains those values at the indices specified by the argument other.

Indices in other may be specified either as a vector of logicals, a vector of integers or as another bitset. If a vector of logicals is specified, it must be of the same size as the bitset. Please note that filtering by another bitset is not a "bitwise and" intersection, and will have the same behavior as providing an equivalent vector of integer indices.

Usage

filter_bitset(bitset, other)

Arguments

Description

Simulates a two-stage process where all individuals in a given source_state sample whether to leave or not with probability rate; those who leave go to one of the destination_states with probabilities contained in the vector destination_probabilities.

Usage

fixed_probability_multinomial_process(
  variable,
  source_state,
  destination_states,
  rate,
  destination_probabilities
)

Arguments

Value

a function which can be passed as a process to simulation_loop.

Description

Simulates infection for age-structured models, where individuals contact each other at a rate given by some mixing (contact) matrix. The force of infection on susceptibles in a given age class is computed as:

$\lambda_{i} = p \sum\limits_{j} C_{i,j} \left( \frac{I_{j}}{N_{j}} \right)$

Where $C$ is the matrix of contact rates, $p$ is the probability of infection per contact. The per-capita probability of infection for susceptible individuals is then:

$1 - e^{-\lambda_{i} \Delta t}$

.

Usage

infection_age_process(
  state,
  susceptible,
  exposed,
  infectious,
  age,
  age_bins,
  p,
  dt,
  mixing
)

Arguments

Value

a function which can be passed as a process to simulation_loop.

Description

Represents a integer valued variable for an individual. This class is similar to CategoricalVariable, but can be used for variables with unbounded ranges, or other situations where part of an individual's state is better represented by an integer, such as household or age bin.

Methods

Public methods

• IntegerVariable$new()

• IntegerVariable$get_values()

• IntegerVariable$get_modulo_differences()

• IntegerVariable$get_index_of()

• IntegerVariable$get_size_of()

• IntegerVariable$queue_update()

• IntegerVariable$queue_extend()

• IntegerVariable$queue_shrink()

• IntegerVariable$size()

• IntegerVariable$.update()

• IntegerVariable$.resize()

• IntegerVariable$save_state()

• IntegerVariable$restore_state()

• IntegerVariable$clone()

Method new()

Create a new IntegerVariable.

Usage

IntegerVariable$new(initial_values)

Arguments

Method get_values()

Get the variable values.

Usage

IntegerVariable$get_values(index = NULL)

Arguments

Method get_modulo_differences()

Return a vector of individuals with 0 modulo difference from input value and the distance being compared

Usage

IntegerVariable$get_modulo_differences(value, difference)

Arguments

Method get_index_of()

Return a Bitset for individuals with some subset of values. Either search for indices corresponding to values in set, or for indices corresponding to values in range $[a,b]$. Either set or a and b must be provided as arguments.

Usage

IntegerVariable$get_index_of(set = NULL, a = NULL, b = NULL)

Arguments

Method get_size_of()

Return the number of individuals with some subset of values. Either search for indices corresponding to values in set, or for indices corresponding to values in range $[a,b]$. Either set or a and b must be provided as arguments.

Usage

IntegerVariable$get_size_of(set = NULL, a = NULL, b = NULL)

Arguments

Method queue_update()

Queue an update for a variable. There are 4 types of variable update:

1. Subset update: The argument index represents a subset of the variable to update. The argument values should be a vector whose length matches the size of index, which represents the new values for that subset.

2. Subset fill: The argument index represents a subset of the variable to update. The argument values should be a single number, which fills the specified subset.

3. Variable reset: The index vector is set to NULL and the argument values replaces all of the current values in the simulation. values should be a vector whose length should match the size of the population, which fills all the variable values in the population

4. Variable fill: The index vector is set to NULL and the argument values should be a single number, which fills all of the variable values in the population.

Usage

IntegerVariable$queue_update(values, index = NULL)

Arguments

Method queue_extend()

extend the variable with new values

Usage

IntegerVariable$queue_extend(values)

Arguments

Method queue_shrink()

shrink the variable

Usage

IntegerVariable$queue_shrink(index)

Arguments

Method size()

get the size of the variable

Usage

IntegerVariable$size()

Method .update()

Usage

IntegerVariable$.update()

Method .resize()

Usage

IntegerVariable$.resize()

Method save_state()

save the state of the variable

Usage

IntegerVariable$save_state()

Method restore_state()

restore the variable from a previously saved state.

Usage

IntegerVariable$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

IntegerVariable$clone(deep = FALSE)

Arguments

Description

Simulates a Bernoulli process where all individuals in a given source state from sample whether or not to transition to destination state to with a individual probability specified by the DoubleVariable object rate_variable.

Usage

multi_probability_bernoulli_process(variable, from, to, rate_variable)

Arguments

Value

a function which can be passed as a process to simulation_loop.

Description

Simulates a two-stage process where all individuals in a given source_state sample whether to leave or not with a individual probability specified by the DoubleVariable object rate_variable; those who leave go to one of the destination_states with probabilities contained in the vector destination_probabilities.

Usage

multi_probability_multinomial_process(
  variable,
  source_state,
  destination_states,
  rate_variable,
  destination_probabilities
)

Arguments

Value

a function which can be passed as a process to simulation_loop.

Description

This is a ragged array which stores doubles (numeric values).

Methods

Public methods

• RaggedDouble$new()

• RaggedDouble$get_values()

• RaggedDouble$get_length()

• RaggedDouble$queue_update()

• RaggedDouble$queue_extend()

• RaggedDouble$queue_shrink()

• RaggedDouble$size()

• RaggedDouble$.update()

• RaggedDouble$.resize()

• RaggedDouble$save_state()

• RaggedDouble$restore_state()

• RaggedDouble$clone()

Method new()

Create a new RaggedDouble

Usage

RaggedDouble$new(initial_values)

Arguments

Method get_values()

Get the variable values.

Usage

RaggedDouble$get_values(index = NULL)

Arguments

Method get_length()

Get the lengths of the indiviudal elements in the ragged array

Usage

RaggedDouble$get_length(index = NULL)

Arguments

Method queue_update()

Queue an update for a variable. There are 4 types of variable update:

1. Subset update: The argument index represents a subset of the variable to update. The argument values should be a vector whose length matches the size of index, which represents the new values for that subset.

2. Subset fill: The argument index represents a subset of the variable to update. The argument values should be a single number, which fills the specified subset.

3. Variable reset: The index vector is set to NULL and the argument values replaces all of the current values in the simulation. values should be a vector whose length should match the size of the population, which fills all the variable values in the population

4. Variable fill: The index vector is set to NULL and the argument values should be a single number, which fills all of the variable values in the population.

Usage

RaggedDouble$queue_update(values, index = NULL)

Arguments

Method queue_extend()

extend the variable with new values

Usage

RaggedDouble$queue_extend(values)

Arguments

Method queue_shrink()

shrink the variable

Usage

RaggedDouble$queue_shrink(index)

Arguments

Method size()

get the size of the variable

Usage

RaggedDouble$size()

Method .update()

Usage

RaggedDouble$.update()

Method .resize()

Usage

RaggedDouble$.resize()

Method save_state()

save the state of the variable

Usage

RaggedDouble$save_state()

Method restore_state()

restore the variable from a previously saved state.

Usage

RaggedDouble$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

RaggedDouble$clone(deep = FALSE)

Arguments

Description

This is a ragged array which stores integers (numeric values).

Methods

Public methods

• RaggedInteger$new()

• RaggedInteger$get_values()

• RaggedInteger$get_length()

• RaggedInteger$queue_update()

• RaggedInteger$queue_extend()

• RaggedInteger$queue_shrink()

• RaggedInteger$size()

• RaggedInteger$.update()

• RaggedInteger$.resize()

• RaggedInteger$save_state()

• RaggedInteger$restore_state()

• RaggedInteger$clone()

Method new()

Create a new RaggedInteger

Usage

RaggedInteger$new(initial_values)

Arguments

Method get_values()

Get the variable values.

Usage

RaggedInteger$get_values(index = NULL)

Arguments

Method get_length()

Get the lengths of the indiviudal elements in the ragged array

Usage

RaggedInteger$get_length(index = NULL)

Arguments

Method queue_update()

Queue an update for a variable. There are 4 types of variable update:

1. Subset update: The argument index represents a subset of the variable to update. The argument values should be a vector whose length matches the size of index, which represents the new values for that subset.

2. Subset fill: The argument index represents a subset of the variable to update. The argument values should be a single number, which fills the specified subset.

3. Variable reset: The index vector is set to NULL and the argument values replaces all of the current values in the simulation. values should be a vector whose length should match the size of the population, which fills all the variable values in the population

4. Variable fill: The index vector is set to NULL and the argument values should be a single number, which fills all of the variable values in the population.

Usage

RaggedInteger$queue_update(values, index = NULL)

Arguments

Method queue_extend()

extend the variable with new values

Usage

RaggedInteger$queue_extend(values)

Arguments

Method queue_shrink()

shrink the variable

Usage

RaggedInteger$queue_shrink(index)

Arguments

Method size()

get the size of the variable

Usage

RaggedInteger$size()

Method .update()

Usage

RaggedInteger$.update()

Method .resize()

Usage

RaggedInteger$.resize()

Method save_state()

save the state of the variable

Usage

RaggedInteger$save_state()

Method restore_state()

restore the variable from a previously saved state.

Usage

RaggedInteger$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

RaggedInteger$clone(deep = FALSE)

Arguments

Description

Class to render output for the simulation.

Methods

Public methods

• Render$new()

• Render$set_default()

• Render$render()

• Render$to_dataframe()

• Render$clone()

Method new()

Initialise a renderer for the simulation, creates the default state renderers.

Usage

Render$new(timesteps)

Arguments

Method set_default()

Set a default value for a rendered output renderers.

Usage

Render$set_default(name, value)

Arguments

Method render()

Update the render with new simulation data.

Usage

Render$render(name, value, timestep)

Arguments

Method to_dataframe()

Return the render as a data.frame.

Usage

Render$to_dataframe()

Method clone()

The objects of this class are cloneable with this method.

Usage

Render$clone(deep = FALSE)

Arguments

Description

Schedules a follow-up event as the result of an event firing.

Usage

reschedule_listener(event, delay)

Arguments

Description

Restore the state of one or more simulation objects. The specified objects are paired up with the relevant part of the state object, and the restore_state method of each object is called.

If the list of object is named, more objects may be specified than were originally present in the saved simulation, allowing a simulation to be extended with more features upon resuming. In this case, the restore_state method of the new objects is called with a NULL argument. Conversly, the list of objects may omit certain entries, in which case their state to be restored is ignored.

Usage

restore_object_state(timesteps, objects, state)

Arguments

Description

Restore the simulation state from a previous checkpoint. The state of passed events and variables is overwritten to match the state they had when the simulation was checkpointed.

Usage

restore_simulation_state(state, variables, events, restore_random_state)

Arguments

Value

the time step at which the simulation should resume.

Description

Save the state of a simulation object or set of objects.

Usage

save_object_state(objects)

Arguments

Value

the saved states of the objects. This has the same shape as the given objects: if a list was passed as an argument, this returns the corresponding list of saved states. If a singular object was passed, this returns just that particular object's state.

Description

Save the simulation state in an R object, allowing it to be resumed later using restore_simulation_state.

Usage

save_simulation_state(timesteps, variables, events)

Arguments

Value

the saved simulation state.

Description

Run a simulation where event listeners take precedence over processes for state changes.

Usage

simulation_loop(
  variables = list(),
  events = list(),
  processes = list(),
  timesteps,
  state = NULL,
  restore_random_state = FALSE
)

Arguments

Value

Invisibly, the saved state at the end of the simulation, suitable for later resuming.

Examples

population <- 4
timesteps <- 5
state <- CategoricalVariable$new(c('S', 'I', 'R'), rep('S', population))
renderer <- Render$new(timesteps)

transition <- function(from, to, rate) {
  return(function(t) {
    from_state <- state$get_index_of(from)
    state$queue_update(
      to,
      from_state$sample(rate)
    )
  })
}

processes <- list(
  transition('S', 'I', .2),
  transition('I', 'R', .1),
  transition('R', 'S', .05),
  categorical_count_renderer_process(renderer, state, c('S', 'I', 'R'))
)

simulation_loop(variables=list(state), processes=processes, timesteps=timesteps)
renderer$to_dataframe()

Description

Describes a targeted event in the simulation. This is useful for events which are triggered for a sub-population.

Super class

individual::EventBase -> TargetedEvent

Methods

Public methods

• TargetedEvent$new()

• TargetedEvent$schedule()

• TargetedEvent$get_scheduled()

• TargetedEvent$clear_schedule()

• TargetedEvent$queue_extend()

• TargetedEvent$queue_extend_with_schedule()

• TargetedEvent$queue_shrink()

• TargetedEvent$.process_listener()

• TargetedEvent$.process_listener_cpp()

• TargetedEvent$.resize()

• TargetedEvent$save_state()

• TargetedEvent$restore_state()

• TargetedEvent$clone()

Method new()

Initialise a TargetedEvent.

Usage

TargetedEvent$new(population_size)

Arguments

Method schedule()

Schedule this event to occur in the future.

Usage

TargetedEvent$schedule(target, delay)

Arguments

Method get_scheduled()

Get the individuals who are scheduled as a Bitset.

Usage

TargetedEvent$get_scheduled()

Method clear_schedule()

Stop a future event from triggering for a subset of individuals.

Usage

TargetedEvent$clear_schedule(target)

Arguments

Method queue_extend()

Extend the target size.

Usage

TargetedEvent$queue_extend(n)

Arguments

Method queue_extend_with_schedule()

Extend the target size and schedule for the new population.

Usage

TargetedEvent$queue_extend_with_schedule(delays)

Arguments

Method queue_shrink()

Shrink the TargetedEvent.

Usage

TargetedEvent$queue_shrink(index)

Arguments

Method .process_listener()

Usage

TargetedEvent$.process_listener(listener)

Method .process_listener_cpp()

Usage

TargetedEvent$.process_listener_cpp(listener)

Method .resize()

Usage

TargetedEvent$.resize()

Method save_state()

save the state of the event

Usage

TargetedEvent$save_state()

Method restore_state()

restore the event from a previously saved state.

Usage

TargetedEvent$restore_state(timestep, state)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

TargetedEvent$clone(deep = FALSE)

Arguments

Description

Updates the category of a sub-population as the result of an event firing, to be used in the TargetedEvent class.

Usage

update_category_listener(variable, to)

Arguments