TransitionClassification: Transition for a classification model
In dymium-org/dymiumCore: A Toolkit for Building a Dynamic Microsimulation Model for Integrated Urban Modelling

Description Arguments Value Construction Fields Methods Note See Also Examples

TransitionClassification performs Monte Carlo simulation on a probabilistic model. In a simpler term, a psuedo random number generator is used to simulate the outcome based on the probability from the model.

By calling the constructor method of TransitionClassification this will initiate the following steps:

initialise(x, model, target, targeted_agents) ->
filter(.data): filter agents to apply the transition to.
mutate(.data): add variables to the data of the filtered agents.
simulate(): simulate the transition outcome using the probabilistic model
postprocess(.sim_result): post-processing the simulation result.

Note that, the order of filter and mutate can be swap by overwriting the mutate_first public field to TRUE. This may be useful in cases where agent selection for the transition depends on one or more derived variables.

To get the simulation result use $get_result().

Create a TransitionClassification object.

`x`	an Entity object
`model`	any objects of type in SupportedTransitionModels.
`target`	a named list where the names corresponds to the choices and the values are the number of agents to choose those choices. This imposes an alignment of the outcomes to an external constraint.
`targeted_agents`	a integer vector that contains ids of the entities in `x` to undergo this
`model_by_id`	see in the public field section.

an R6::R6Class object

1	TransitionClassification$new(x, model, target = NULL, targeted_agents = NULL)

x :: R6::R6Class
An Entity object or its inheritances.
model :: any object in SupportedTransitionModels
A model object to be used to simulate transition.
target :: a named list()
(Default as NULL). Target or A named list where its names is a subset of to the choices in model to be selected and its values are the number of agents to choose those choices. See the note section for more details.
targeted_agent :: integer()
(Default as NULL) An integer vector that contains agents' ids of the Entity in x to undergo the transition. If this is given then target will be ignored.
model_by_id :: logical(1)
This flag is to indicate whether the model object is meant to be matched by the id column of the entity object in x or not. It should be noted that this flag only matters if the model object is of type data.table::data.table() where it must contains a numeric column called prob or list columns of type numeric and character called probs and choices. The model object must have a column which its name matches with the id column of the entity object in x.

model_by_id :: (logical(1))
See argument in the construction section.
mutate_first:: logical(1)
Default as FALSE, this flag is used to indicate whether the attribute data from the Agent in x should be mutated ($mutate(.data)) before filtered ($filter(.data)).

filter(.data)
(data.table::data.table()) -> [data.table::data.table()]
(By default, first of the preprocessing steps)
By default this method returns the input .data. This method can be overwrite to give the user the flexibility to 'filter' the data prior to making prediction by the given model. Filtering for eligible agents for this transition can be done in this step.
mutate(.data)
(data.table::data.table()) -> [data.table::data.table()]
(By default, second of the preprocessing steps)
By default this method returns the input .data. This method can be overwrite to give the user the flexibility to 'mutate' the data prior to making prediction by the given model. Adding derived variables and historical life course of the agents can be done in this step.
update_agents(attr)
(character(1))
Update the attribute data of the agents that undergo the transition event.
get_result(ids)
(integer()) -> data.table::data.table
Returns the simulation result in a data.table::data.table format with two columns id and response.
get_nrow_result()
Returns the number of rows in the simulation result.
get_decision_maker_ids(response_filter = NULL)
(character()) -> (integer())
Returns ids of the agents that have their response equal to response_filter.

target is used ensures that the aggregate outcome of the transition matches a macro-level outcome as defined in target. This is known as 'alignment' see, Li, J., & O'Donoghue, C. (2012). Evaluating binary alignment methods in microsimulation models. For example, in a transition where the probabilistic model predicts only two outcomes, a binary model, "yes" and "no". If the target is a list of yes = 10 and no = 20 (i.e.10 20'), this will ensure that there will be 10 decision makers whom select 'yes' and 20 decision makers that select 'no'. However, this doesn't mean that all decision makers have an equal odd of select 'yes' or 'no', the odd is still to be determined by the given probalistic model. See alignment for more detail.

TransitionRegression and Trans.

# create a Individual agent object
Ind <- Individual$new(.data = toy_individuals, id_col = "pid")

# create a probabilistic model
driver_status_rate <- data.table::data.table(
  sex = c("male", "female"),
  probs = list(c(0.3, 0.7), c(0.4, 0.6)),
  choices = list(c("can drive", "cannot drive"), c("can drive", "cannot drive"))
)

# create a Transition for driver status
TransitionCandrive <- R6::R6Class(
  classname = "TransitionCandrive",
  inherit = TransitionClassification
)

TransCanDrive <- TransitionCandrive$new(x = Ind, model = driver_status_rate)

barplot(
  table(TransCanDrive$get_result()[["response"]]),
  main = "Transition result: driver status",
  col = c("steelblue", "salmon")
)