Event Queue

The event queue is a crucial part of the MASH framework as it handles all events a human could preform. It follows a generic structure that any extensions of MASH should mirror exactly. When extensions are added they must include at a minimum functions of the form add2Q_XX(), event_XX(), XX() for events to be properly called. Descriptions and examples follow.

Event Queue Management

addEvent2Q

addEvent2Q() is a crucial function that manages the proper placement of new events to a person’s event queue. This function is not called directly but is called by the add2Q_XX() family of functions. This function takes two arguments:

• ixH: index of human
• event: a function of the form event_XX(t, PAR)

Below is a description of how the event queue works and should be followed for any future modules.

addEvent2Q(ixH, event){
  ...
}

add2Q_XX

add2Q_XX() is a generic format for adding event XX to a particular person’s event queue. This generic form is used by all functions of this type and are called when some conditions are met that requires a future event to be queued. The function takes two or three arguments:

• ixH: index of human
• t: time the event will occur
• PAR: optional argument of generic event parameters

add2Q_XX(ixH, t, PAR){
  addEvent2Q(ixH, event_XX(t, PAR))
}

event_XX

event_XX() is a generic format for an event. This function is a wrapper that creates a list structure that describes a single event which is placed into a person’s event queue by addEvent2Q(). This list will lie dormant in the event queue until it the event occurs. The function takes one or two arguments:

• t: time the event will occur
• PAR: optional argument of generic event parameters

It is important that the list returned by this function exactly match the format below as this is the object that will enter the person’s event queue and will determine how the event will occur at the appropriate time. The named list has four named slots:

• t: time the event will occur
• PAR: event parameters (if no parameters needed, set to NULL)
• F: a function of the form F(ixH, t, PAR) that will execute the event
• tag: string of the event name (used for fast lookup)

event_XX(t, PAR){
  list(t = t, PAR = PAR, F = XX, tag = "XX")
}

XX

XX() is a generic format for the actual event. This function is called from the main human event queue simulation through runHumanEventQ. This function may directly modify the human object that it is acting upon, and may itself queue up more events. It takes three arguments:

• ixH: index of human
• t: time the event will occur
• PAR: generic event parameters

XX(ixH, t, PAR){
  # preform arbitrary number of operations on human ixH
  # may itself call functions of add2Q_XX family
}

Example

The following is an example of how the various event queue functions work together, taken from the PfSI module. Points of interest:

• simbite_PfSI(), the equivalent of XX() in the generic family is able to queue multiple future events from itself.
• add2Q_startPfSI() shows the versatility of the PAR argument; virtually any object can be passed in the third slot because it is not directly handled by addEvent2Q() as long as PAR is appropriately handled by other functions in the event family.

add2Q_startPfSI <- function(ixH, t, pfid){
  addEvent2Q(ixH, event_startPfSI(t, pfid))
}

event_startPfSI <- function(t, pfid){
  #if(NOISY == TRUE) {print(c(t=t,"adding infection")); browser()}
  if(NOISY == TRUE) {print(c(t=t,"adding infection"))}
  list(t=t, PAR=pfid, F=infectHuman_PfSI, tag="infectHuman_PfSI")
}

infectHuman_PfSI <- function(ixH, t, pfid){
  if(NOISY == TRUE){print("infectHuman")}
  #Infect
  if(HUMANS[[ixH]]$Pathogens$Pf$infected == FALSE & HUMANS[[ixH]]$Pathogens$Pf$chemoprophylaxis == FALSE){
      if(NOISY==TRUE) print("Infect")
      PfSIHistory(ixH, t, "I")
      HUMANS[[ixH]]$Pathogens$Pf$infected <<- TRUE
      HUMANS[[ixH]]$Pathogens$Pf$t0 <<- t
      HUMANS[[ixH]]$Pathogens$Pf$pfid <<- pfid
      if(rbinom(1,1,FeverPf)){
        add2Q_feverPfSI(ixH, t)
      }
      add2Q_endPfSI(ixH, t, pfid)
    }
}

Human Object