tomstats: tomstats

Description

Computes statistics for modeling relational event history data with the tie-oriented relational event model.

Usage

tomstats(
  tie_effects,
  reh,
  memory = c("full", "window", "decay", "interval"),
  memory_value = NA,
  first = 2,
  last = Inf,
  display_progress = FALSE,
  sampling = FALSE,
  samp_num = 10L,
  seed = NULL,
  attr_actors = NULL,
  attr_dyads = NULL
)

Value

An object of class 'tomstats'. Array with the computed statistics, where rows refer to time points, columns refer to potential relational event (i.e., potential edges) in the risk set and slices refer to statistics. Statistics are computed once per unique time point (per-timepoint "pt" method), so the number of rows in the output equals reh$M (the number of unique time points), which may be less than the total number of observed events when simultaneous events are present. The 'tomstats' object has the following attributes:

model: Type of model that is estimated.
formula: Model formula, obtained from the formula inputted to 'tie_effects'.
riskset: The risk set used to construct the statistics.

Arguments

tie_effects: an object of class "formula" (or one that can be coerced to that class): a symbolic description of the tie_effects in the model for which statistics are computed, see 'Details' for the available effects and their corresponding statistics
reh: an object of class "remify" characterizing the relational event history. May also be a remify_durem object for duration relational event models.
memory: The memory to be used. See `Details'.
memory_value: Numeric value indicating the memory parameter. Default is NA, which is only valid for memory = "full" (no memory parameter required). See `Details'.
first: an optional integer value, specifying the index of the first unique time point event in the relational event history for which statistics must be computed (see 'Details'). Default is 2: the first event has no history and is used only to initialize statistics, not to fit the model.
last: an optional integer value, specifying the index of the last unique time point in the relational event history for which statistics must be computed (see 'Details')
display_progress: should a progress bar for the computation of the endogenous statistics be shown (TRUE) or not (FALSE)?
sampling: Logical. If TRUE, statistics are computed using case–control (dyad) sampling rather than the full risk set. Default FALSE.
samp_num: Integer. Number of dyads to include per event when sampling = TRUE. Must be smaller than or equal to the size of the active risk set. Ignored when sampling = FALSE.
seed: Optional integer. Random seed used for dyad sampling. Setting this ensures reproducible sampling across calls. If NULL, the current RNG state is used.
attr_actors: optionally, an object of class "data.frame" that contains exogenous attributes for actors (see Details).
attr_dyads: optionally, an object of class data.frame or matrix containing attribute information for dyads (see Details).

Effects

The statistics to be computed are defined symbolically and should be supplied to the effects argument in the form ~ effects. The terms are separated by + operators. For example: tie_effects = ~ inertia() + otp(). Interactions between two effects can be included with * operators. For example: tie_effects = ~ inertia()*otp(). A list of available effects can be obtained with tie_effects().

The majority of the statistics can be scaled in some way, see the documentation of the scaling argument in the separate effect functions for more information on this.

The majority of the statistics can account for the event type included as a dependent variable, see the documentation of the consider_type argument in the separate effect functions for more information on this.

Note that events in the relational event history can be directed or undirected. Some statistics are only defined for either directed or undirected events (see the documentation of the statistics). Note that undirected events are only available for the tie-oriented model.

Memory

The default `memory` setting is `"full"`, which implies that at each time point $t$ the entire event history before $t$ is included in the computation of the statistics. Alternatively, when `memory` is set to `"window"`, only the past event history within a given time window is considered (see Mulders & Leenders, 2019). This length of this time window is set by the `memory_value` parameter. For example, when `memory_value = 100` and `memory = "window"`, at time point $t$ only the past events that happened at most 100 time units ago are included in the computation of the statistics. A third option is to set `memory` to `"interval"`. In this case, the past event history within a given time interval is considered. For example, when `"memory_value" = c(50, 100)` and `memory = "interval"`, at time point $t$ only the past events that happened between 50 and 100 time units ago are included in the computation of the statistics. Finally, the fourth option is to set `memory` to `"decay"`. In this case, the weight of the past event in the computation of the statistics depend on the elapsed time between $t$ and the past event. This weight is determined based on an exponential decay function with half-life parameter `memory_value` (see Brandes et al., 2009).

Event weights

Note that if the relational event history contains a column that is named ``weight'', it is assumed that these affect the endogenous statistics. These affect the computation of all endogenous statistics with a few exceptions that follow logically from their definition (e.g., the recenyContinue statistic does depend on time since the event and not on event weights).

Subset the event history using 'first' and 'last'

It is possible to compute statistics for a segment of the relational event sequence, based on the entire event history. This is done by specifying the 'first' and 'last' values as the indices for the first and last event times for which statistics are needed. For instance, setting 'first = 5' and 'last = 5' calculates statistics for the 5th event in the relational event sequence. Note that in cases of simultaneous events, 'first' and 'last' correspond to the indices of the first and last unique event timepoints. unique event timepoints for which statistics are needed. For example, if 'first = 5' and 'last = 5', statistics are computed for the 5th unique timepoint in the relational event sequence, considering all events occurring at unique timepoints 1-4.

Examples

Run this code

library(remstats)

# Tie-oriented model
eff <- ~ inertia():send("extraversion", attr_actors = info) + otp()
reh_tie <- remify::remify(edgelist = history, model = "tie")
remstats(reh = reh_tie, tie_effects = eff)

# Tie-oriented model with case control sampling
eff <- ~ inertia():send("extraversion", attr_actors = info) + otp()
reh_tie <- remify::remify(edgelist = history, model = "tie")
remstats(reh = reh_tie, tie_effects = eff, sampling = TRUE, samp_num = 5L)

Run the code above in your browser using DataLab