remulateActor: Simulate Relational Event Data - Actor-Oriented model

View source: R/remulateActor.R

remulateActorR Documentation

Simulate Relational Event Data - Actor-Oriented model

Description

A function to simulate relational event data by sampling from an actor-oriented relational event model.

Usage

remulateActor(
  rateEffects,
  choiceEffects,
  actors,
  endTime,
  events = NULL,
  startTime = 0,
  initial = 0,
  riskset = NULL,
  memory = c("full", "window", "window_m", "decay"),
  memoryParam = NULL
)

Arguments

rateEffects

A formula object specifying the statistics used to simulate the network under the actor rate sub-model.

choiceEffects

A formula object specifying the statistics used to simulate the network under the receiver choice sub-model.

actors

A numeric or character vector representing the actor names.

endTime

A numeric value specifying the end time up to which the network should be simulated.

events

[Optional] An integer specifying the maximum number of events to simulate.

startTime

[Optional] A numeric value (default = 0) indicating the time at which the simulation should start.

initial

[Optional] A numeric or data.frame object (default = 0) specifying how to initialize the network. - If an integer is provided, it represents the number of random events to sample before beginning data generation. - If a data.frame is provided with columns (time, sender, receiver), it serves as an edgelist of initial events, after which subsequent events are predicted.

riskset

[Optional] A matrix with columns (sender, receiver) defining a custom risk set.

memory

[Optional] A string (default = "full") specifying the memory type used for computing statistics. - '"full"': Uses the entire event history. - '"window"': Considers only events occurring within a specified time window. - '"window_m"': Considers only a specified number of most recent events. - '"decay"': Applies an exponential decay, where older events contribute less based on elapsed time.

memoryParam

[Optional] A numeric value (> 0) defining the memory parameter based on the selected memory type: - '"window"': Length of the time window. - '"window_m"': Number of past events to consider. - ‘"decay"': Half-life (i.e., time until an event’s weight is reduced to half).

Details

#' If time is irrelevant and only a specific number of events are desired, set time to Inf. If both time and events are supplied then the function stops simulating whenever the first stop condition is met

A list of available statistics for actor rate model. See remulateActorEffects for details on effects:

  • baseline()

  • indegreeSender()

  • outdegreeSender()

  • totaldegreeSender()

  • ospSender()

  • otpSender()

  • send()

  • interact()

A list of available statistics for receiver choice model. See remulateActorEffects for details on effects: :

  • inertia()

  • reciprocity()

  • indegreeReceiver()

  • outdegreeReceiver()

  • totaldegreeReceiver()

  • otp()

  • itp()

  • osp()

  • isp()

  • psABBA()

  • psABBY()

  • psABXA()

  • psABXB()

  • psABXY()

  • psABAY()

  • recencyContinue()

  • recencySendReceiver()

  • recencyReceiveReceiver()

  • rrankReceive()

  • receive()

  • dyad()

  • same()

  • average()

  • difference()

  • minimum()

  • maximum()

  • interact()

Value

An object of class "remulateActor". A data.frame containing the simulated event sequence with columns (time, sender, receiver). The "remulateActor" object has the following attributes::

evls

A matrix containing the event list with columns (dyad, time), where dyad represents the index of the (sender, receiver) pair in the risk set.

rateStatistics

An array of dimensions M x N x P, where: - M is the number of events, - N is the number of actors, - P is the number of sender rate statistics.

choiceStatistics

An array of dimensions M x D x Q, where: - M is the number of events, - D is the number of dyads in the risk set, - Q is the number of receiver choice statistics.

rateParams

A named list of rate model parameters corresponding to the specified rate statistics.

choiceParams

A named list of choice model parameters corresponding to the specified choice statistics.

riskset

A matrix with columns (sender, receiver) representing the risk set used in the simulation.

actors

A data.frame mapping the actor names provided by the user to the integer IDs used in internal computations.

#'

initial

A A numeric or data.frame object representing the network initialization, which can be a number of random initialization events or a data.frame specifying pre-existing ties.

rateEffects

A formula object specifying the effects included in the rate sub-model.

choiceEffects

A formula object specifying the effects included in the choice sub-model.

density

A numeric value indicating the density of the generated network, defined as the number of observed ties divided by N*(N-1), where N is the number of actors.

References

Lakdawala, R., Mulder, J., & Leenders, R. (2025). *Simulating Relational Event Histories: Why and How*. arXiv:2403.19329.

Examples

 # To generate events up to time '50' in a network of 25 actors with 
 # 200 random initial events
 
 # Exogenous attributes data.frame
 cov <- data.frame(
   id   = 1:25, 
   time = rep(0, 25), 
   sex  = sample(c(0,1), 25, replace = TRUE, prob = c(0.4, 0.6)), 
   age  = sample(20:30, 25, replace = TRUE) 
 )
 
 # Effects specification
 rateform <- ~ remulate::baseline(-6) + 
              remulate::indegreeSender(0.01) + 
              remulate::send(0.02, variable = "age", attr_actors = cov) + 
              remulate::interact(0.01, indices = c(2, 3))
 
 choiceform <- ~ remulate::inertia(0.01) + 
               remulate::reciprocity(-0.03) + 
               remulate::interact(0.01, indices = c(2, 1))
 
 # Calling remulateActor
 remulate::remulateActor(
   rateform, 
   choiceform, 
   actors  = 1:25, 
   endTime = 100, 
   initial = 200, 
   events  = 500, 
 )
  
 # To predict events, given an edgelist of initial events
 initialREH <- data.frame(
   time = seq(0.5, 100, 0.5), 
   sender = sample(1:25, 200, TRUE), 
   receiver = sample(1:25, 200, TRUE)
 )
 
 remulate::remulateActor(
   rateform, 
   choiceform, 
   actors  = 1:25, 
   endTime = 200, 
   initial = initialREH, 
   events  = 500
 )

remulate documentation built on April 16, 2025, 5:09 p.m.