Return the Historical Contacts (Partners) of a Set of Index Nodes

Pulls every cumulative-edgelist row touching one of the supplied "index" nodes, returning each (index, partner) pair together with the partnership start/stop times and the network layer. This is the building block for contact tracing over the simulated network history.

Usage

get_partners(
  dat,
  index_posit_ids,
  networks = NULL,
  truncate = Inf,
  only.active.nodes = FALSE
)

Arguments

dat

Main netsim_dat object containing a networkDynamic object and other initialization information passed from netsim().

index_posit_ids

The positional IDs of the indexes of interest.

networks

Numerical indexes of the networks to extract the partnerships from. (May be > 1 for models with multi-layer networks.) If NULL, extract from all networks.

truncate

After how many time steps a partnership that is no longer active should be removed from the output. See the Truncation section.

only.active.nodes

If TRUE, then inactive (e.g., deceased) partners will be removed from the output.

Value

A data.frame with 5 columns:

• index: the unique IDs of the indexes.

• partner: the unique IDs of the partners/contacts.

• start: the time step at which the edge started.

• stop: the time step in which the edge stopped; if ongoing, then NA is returned.

• network: the numerical index for the network on which the partnership/contact is located.

Details

Indexes are passed as positional IDs but the output uses unique IDs, because partners may include nodes that have already departed (and thus no longer have a positional ID). Use get_unique_ids() and get_posit_ids() to convert between the two systems.

The truncate argument here filters by edge age: only edges whose stop step is within truncate time steps of the current step are kept (active edges are always included). It operates on whatever history is already stored in the cumulative edgelist; it cannot recover edges that were dropped earlier by update_cumulative_edgelist() or by control$truncate.el.cuml.

See also

get_cumulative_degree() for a partner count per index; get_cumulative_edgelist() / get_cumulative_edgelists_df() for the underlying edgelist; get_unique_ids() / get_posit_ids() for ID conversion.

Other cumulative_edgelist: as_cumulative_edgelist(), dedup_cumulative_edgelist(), get_cumulative_degree(), get_cumulative_edgelist(), get_cumulative_edgelists_df(), reachable-nodes, update_cumulative_edgelist()

Examples

if (FALSE) { # \dontrun{
# Contacts of nodes 1..10 across all networks within the last 30 steps,
# excluding partners who have since departed:
get_partners(dat,
             index_posit_ids = 1:10,
             truncate = 30,
             only.active.nodes = TRUE)
} # }