linkEvents: Link dynamic events to a nodeset or a network

Description

Link events stored in data frames that modify attributes of the nodeset or modify ties in a network.

Usage

linkEvents(x, ...)
# S3 method for nodes.goldfish
linkEvents(x, changeEvents, attribute, ...)
# S3 method for network.goldfish
linkEvents(x, changeEvents, nodes = NULL, nodes2 = NULL, ...)
# S3 method for default
linkEvents(x, ...)

Value

an object with the same class as the object x. For objects of class network.goldfish the attribute events with the name of the event data frame passed through with the argument changeEvents. For objects of class nodes.goldfish attibutes events and dynamicAttribute are modified with name of the objects passed through with the arguments changeEvents and attribute respectively.

Arguments

x: Either a nodeset (nodes.goldfish object) or a network (network.goldfish object)
...: additional arguments to be passed to the method.
changeEvents: The name of a data frame that represents a valid events list.
attribute: a character vector indicating the names of the attributes that should be updated by the specified events (ONLY if the object is a nodeset).
nodes: a nodeset (data.frame or nodes.goldfish object) related to the network (ONLY if x is a network)
nodes2: an optional nodeset (data.frame or nodes.goldfish object) related to the network (ONLY if x is a network)

Details

The data frame that contains the events must contain variables with specific names depending if they refer to dynamic attributes or dynamic networks.

For dynamic networks stored in object of class network.goldfish the changeEvents data frame must contain the following variables:

time: numeric or POSIXct (see base::as.Date()) variable containing the time-stamps when the event happen.
sender: character variable indicating the label of the sender of the event.
receiver: character variable indicating the label of the receiver of the event.

See the bilatchanges and contigchanges data frames in the Fisheries_Treaties_6070 datasets for examples of event data frames that relate with dynamic networks.

For dynamic attributes stored in object of class nodes.goldfish the changeEvents data frame must contain the following variables:

time: numeric or POSIXct (see base::as.Date()) variable containing the time-stamps when the event happen.
label: character variable indicating the label of the node for which the attribute changes.

See sovchanges, regchanges and gdpchanges data frames in the Fisheries_Treaties_6070 datasets for examples of event data frames that relate with dynamic attributes

For both cases an additional variable indicates the change in value of either the ties or attributes. The class of this variable must be the same as the tie value or attribute value that will be updated, i.e., when the present variable is dynamic the updating values must be logical (see defineNodes() for a description of this variable. There are two possibilities on how to specify those changes but only one can be used at a time:

increment

with a numerical value that represent the increment (when it's positive value) or the decrement (when it's a negative value) of the dynamic element from their past value (with respect to the time value).

In the Social_Evolution dataset the calls data frame contains the calling events between students where the increment represent a new call. With every new call the dyad (sender-receiver) increase the count of calls that had happen in the past.

replace

contains the value that would replace at point-time time the attribute or tie value. It is usually the way to represent changes in node attributes.

In the Fisheries_Treaties_6070 dataset the sovchanges, regchanges and gdpchangesdata frames are examples where the replace variable is used to specify attribute changes and their class match with the variable in the node set.

Dynamic network attributes can be also defined using the replace variable. The contigchanges data frame in the Fisheries_Treaties_6070 dataset, and friendship data frame in the Social_Evolution are examples of this.

Examples

Run this code

actors <- data.frame(
  actor = 1:5, label = paste("Actor", 1:5),
  present = TRUE, gender = sample.int(2, 5, replace = TRUE)
)
actors <- defineNodes(nodes = actors)
callNetwork <- defineNetwork(nodes = actors)

# Link events to a nodeset
compositionChangeEvents <- data.frame(
  time = c(14, 60),
  node = "Actor 4",
  replace = c(FALSE, TRUE)
)
actorsnew <- linkEvents(
  x = actors, attribute = "present", changeEvents = compositionChangeEvents
)

# Link events to a Network
calls <- data.frame(
  time = c(12, 27, 45, 56, 66, 68, 87),
  sender = paste("Actor", c(1, 3, 5, 2, 3, 4, 2)),
  receiver = paste("Actor", c(4, 2, 3, 5, 1, 2, 5)),
  increment = rep(1, 7)
)
callNetwork <- linkEvents(
  x = callNetwork, changeEvent = calls, nodes = actors
)