Package 'Dynet'

Description

The same operation as add_ties(), with one extra guarantee: the network must already be directed, so from and to keep the direction the caller means. Adding an arc to an undirected network raises a condition of class dynet_needs_directed rather than silently recording a symmetric tie.

Usage

add_arcs(dn, data, loops = FALSE)

Arguments

Value

A new directed dynet object carrying the added spells, with the same structure as the input.

See Also

add_ties(), which does not require a directed network.

Examples

dn <- dynet(data.frame(from = "A", to = "B", start = 0, end = 1))
dn <- add_nodes(dn, "C")
add_arcs(dn, data.frame(from = "B", to = "C", start = 1, end = 2))

Description

Add nodes to a temporal network

Usage

add_nodes(dn, data)

Arguments

Details

Existing nodes and attributes are unchanged. Missing attribute values are filled with typed NA. If the source has a cograph grouping, each new node must supply its group through a groups column in data or through the source attribute from which that grouping was derived; otherwise a condition of class dynet_missing_group is raised.

Value

A new dynet object, of the same class and structure as the input, with the added nodes represented as implicit always-active isolates until ties or vertex activity are supplied. The input is unchanged.

Examples

dn <- dynet(data.frame(from = "A", to = "B", start = 0, end = 1))
add_nodes(dn, "C")

Description

Add temporal ties

Usage

add_ties(dn, data, loops = FALSE)

Arguments

Details

Added times use the existing network clock. A sessioned network requires an existing session label on every row; mutation does not create a new session scheme. Implicit observation support expands to include the new raw ties, while explicit observation support remains fixed. Added raw rows are interval-format tie identities even when the source was originally a contact, threaded, or co-presence log.

Value

A new dynet object, of the same class and structure as the input. The input is unchanged; canonical temporal ties and every flattened cograph field are rebuilt together.

Examples

dn <- dynet(data.frame(
  from = "A", to = "B", start = 0, end = 1
))
dn <- add_nodes(dn, "C")
add_ties(dn, data.frame(from = "B", to = "C", start = 1, end = 2))

Description

Add declared vertex-activity spells

Usage

add_vertex_spells(dn, data)

Arguments

Value

A new dynet object, class c("dynet", "netobject", "cograph_network"), with the network's existing activity and data canonicalised together, so an added spell that overlaps or abuts an existing one for the same vertex is merged into it and canonical spell identifiers may change. Raises dynet_unknown_node for a vertex the network does not have, and dynet_bad_input when data is not a nonempty data frame, and dynet_incompatible_vertex_spells when session is supplied to a network with no session scheme – the same refusal update_vertex_spells() makes, rather than dropping the label.

Examples

dn <- dynet(school_contacts)
present <- data.frame(node = c("Ana", "Ben"), start = 0, end = 10)
enrolled <- set_vertex_spells(dn, present)
extended <- add_vertex_spells(enrolled,
                              data.frame(node = "Cara", start = 5, end = 20))
as.data.frame(extended, what = "vertex_spells")

Description

Draws the network bin by bin over the measurement grid and writes the frames to an animated GIF or a video. The grid is the same four arguments every measuring verb takes, so an animation shows exactly what snapshots() tabulates and what plot(dn, type = "snapshots") draws as a filmstrip, with the bins joined by motion.

Usage

animate(
  dn,
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  sessions = c("bounded", "collapse"),
  layout = "spring",
  measure = NULL,
  tween = 6L,
  fps = 12,
  file = tempfile(fileext = ".gif"),
  loop = TRUE,
  width = 800L,
  height = 800L,
  res = 120,
  palette = "okabe",
  tie_states = TRUE,
  timeline = TRUE,
  absent = c("fade", "away", "hide"),
  isolates = c("fade", "show", "hide"),
  ease = c("dwell", "continuous"),
  max_displacement = 0.08,
  anchor_strength = 1,
  layout_args = list(),
  seed = 42L,
  ...
)

Arguments

Details

Frames. Each bin is drawn tween times. Between one bin and the next the vertices glide to their new positions, a tie that is about to appear fades in and one that is about to vanish fades out, and a vertex whose measure changes grows or shrinks. Under ease = "dwell", the default, the motion follows the smoothstep curve, so each bin holds still before it starts to change and the bins can be read one by one. Under ease = "continuous" nothing holds still: positions follow a Catmull-Rom spline through the bins, so a vertex moving across several bins traces one smooth path, and fades are linear. tween = 1 gives one frame per bin with hard cuts. A film that feels episodic usually has a grid whose bins do not overlap; a sliding window, step smaller than window, smooths the data itself, since a tie then persists across several bins.

Layouts. Under every layout but "relaxed" a vertex keeps one position for the whole animation, so the only thing that moves is the ties; those are the layouts to read structure from. "spring", the default, lays out the union of every frame once with cograph::layout_spring(), so pairs that met often sit close. "circle" and "oval" are rings, in vertex order. "groups" puts each partition on its own ring and needs a network built with ⁠groups = ⁠. "relaxed" lays each frame out again, seeded from the previous one and held near it by max_displacement and anchor_strength, then smooths every vertex's path with a centred triangular kernel over one bin each side; clusters can form and dissolve without vertices jumping, and no vertex moves further than max_displacement between consecutive bins. Each relaxed frame is framed by its active vertices: a vertex that is absent or has no tie in the bin is held at the border of that frame rather than drifting outward under repulsion, which would shrink the picture. layout_args tunes the spring layout for both. A data frame with columns name (or node), x and y fixes the positions yourself.

What is drawn. Tie width follows weight on one scale fixed across the whole animation, so a tie of the same weight has the same width in a quiet frame and a busy one. With tie_states = TRUE a tie forming during a transition is dotted and green, one persisting is solid and grey, and one dissolving is dashed and vermilion, so the distinction survives without colour. With measure given, node size follows that measure, again on one scale across every frame, with the area of the circle proportional to the measure's position in its range; see the argument for the three forms it takes.

Absence and idleness. A vertex that is not present in a bin, under declared vertex activity or observation bounds, is drawn as absent says: faded in place, parked out of sight at the edge of the layout and gliding in when it arrives and out when it leaves, or hidden in place. A network built without vertex activity has every vertex present in every bin; set_vertex_spells(dn, "ties") declares each vertex present from its first tie to its last. A vertex that is present but has no tie in a bin is drawn as isolates says. With timeline = TRUE a strip under the network shows the grid with a marker at the current time and the key to the drawing.

Files. The extension of file chooses the encoder: .gif is written by the gifski package, .mp4 and .webm by the av package. A video needs even pixel dimensions. Writing the file is the point of the verb, but the tidy bin table is still what comes back, so the animation can be described without opening it.

Value

An object of class "dynet_animation": a tidy data frame with one row per bin and columns bin, frame (the first rendered frame of the bin), time (the bin's label on the network's time scale), window_start and window_end (its bounds), nodes (vertices present), idle (of those, vertices with no tie), ties (ties drawn), forming (ties not active in the previous bin, NA for the first), dissolving (ties not active in the next bin, NA for the last), and file (the same on every row). These are counts of what the picture shows, not the risk-set accounting of events(). The rendered-frame schedule is available through as.data.frame(x, what = "frames"). Returned invisibly, since writing the file is the verb's purpose.

Conditions

Raises dynet_unknown_format for a file extension other than .gif, .mp4 or .webm; dynet_needs_gifski or dynet_needs_av when the encoder that extension needs is not installed; dynet_needs_cograph when cograph is not; dynet_empty_result when the grid holds no bin that can be drawn; dynet_unknown_attribute for layout = "groups" on a network without a partition or a labels naming no vertex attribute; dynet_missing_column and dynet_unknown_node for a coordinate table that is incomplete; dynet_unknown_measure for a measure that is neither a measure centrality_series() offers nor a numeric vertex attribute, and whatever centrality_series() raises for one it refuses; dynet_bad_input for a centrality_series() result that is not node-level or lands on none of the bins, and a warning of class dynet_partial_measure when it lands on only some; and dynet_bad_input for a non-positive fps, tween, width, height or res, an odd video size, a loop that is neither logical nor a positive whole number, or a negative max_displacement or anchor_strength.

See Also

snapshots() for the same grid as a table, plot.dynet() with type = "snapshots" for it as a static filmstrip, and centrality_series() for the measures node size can follow.

Examples

if (requireNamespace("gifski", quietly = TRUE) &&
  requireNamespace("cograph", quietly = TRUE)) {
  dn <- dynet(school_contacts)
  frames <- animate(dn = dn, end = 8, step = 4, window = 4, tween = 2)
  frames
  summary(frames)
}

if (requireNamespace("av", quietly = TRUE) &&
  requireNamespace("cograph", quietly = TRUE)) {
  dn <- dynet(school_contacts)
  file <- tempfile(fileext = ".mp4")
  video <- animate(dn = dn, end = 8, step = 4, tween = 2, measure = "degree", file = file)
  summary(video)
}

Description

Imports a temporal network held in another R representation, so that every Dynet verb applies to it. A method is supplied for networkDynamic objects; the method for dynet is the identity.

Usage

as_dynet(x, ...)

## S3 method for class 'dynet'
as_dynet(x, ...)

Arguments

Value

A dynet() temporal network: an object of class c("dynet", "netobject", "cograph_network") carrying the tie ledger, the node table and the construction metadata. The dynet method is the identity, returning x unchanged, so as_dynet() is safe to call on an object that is already a temporal network.

See Also

as_dynet.networkDynamic(), which imports a networkDynamic object.

Examples

dn <- dynet(data.frame(from = "A", to = "B", start = 0, end = 1))
as_dynet(dn)
dn <- dynet(school_contacts)
same <- as_dynet(dn)
same

Description

Converts the edge-activity spell ledger, observation support, explicit vertex activity, weights, static vertex attributes, and static edge attributes of a networkDynamic object. Integer vertex identifiers are replaced by a complete unique vertex attribute. By default Dynet tries Name, Label, and then vertex.names, in that order.

Usage

## S3 method for class 'networkDynamic'
as_dynet(
  x,
  name_attribute = NULL,
  group_attribute = NULL,
  weight_attribute = "weight",
  session_attribute = NULL,
  interval = NULL,
  active_default = TRUE,
  import_edge_attributes = TRUE,
  ...
)

Arguments

Details

Dynamic edge attributes other than activity itself are not part of the networkDynamic spell-list interface and are therefore not imported. Ordinary per-edge attributes are repeated onto every imported spell of the corresponding aggregate edge, matched on the canonical endpoint order dynet() stores, so an undirected pair carries its own attributes.

Value

A dynet() temporal network: an object of class c("dynet", "netobject", "cograph_network") whose spell table has one row per imported edge-activity spell, with the legacy vertex and edge attributes, observation support, vertex activity and censor flags carried across. Its metadata additionally carries legacy_source = "networkDynamic", the chosen legacy_name_attribute, the retained legacy_edge_attributes and any legacy_edge_attribute_renames.

See Also

as_dynet(), the generic.

Examples

if (requireNamespace("networkDynamic", quietly = TRUE) &&
    requireNamespace("network", quietly = TRUE)) {
  spells <- data.frame(onset = c(0, 1), terminus = c(2, 3),
                       tail = c(1, 2), head = c(2, 3))
  legacy <- networkDynamic::networkDynamic(edge.spells = spells)
  network::set.vertex.attribute(legacy, "Name", c("A", "B", "C"))
  dn <- as_dynet(legacy)
  as.data.frame(dn)
}

Description

Tidy tables from a temporal network

Usage

## S3 method for class 'dynet'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("edges", "nodes", "bins", "network", "observations", "observed_edges",
    "vertex_spells"),
  measure = NULL,
  sessions = c("bounded", "collapse", "separate"),
  start = NULL,
  end = NULL,
  ...
)

Arguments

Value

A plain data.frame, one row per whatever what names.

"edges": one row per unchanged raw spell, with from, to, start, end, duration and weight. A session column is present when the network was built with sessions, onset_censored and terminus_censored when interval censoring was declared explicitly, and any column the construction carried through – thread for a threaded log, group for a co-presence log.

"observations": one row per canonical observation component, with observation, start, end, duration and instant.

"observed_edges": one row per derived observation fragment, with raw_spell, observation and fragment locating it, from, to, start, end (clipped to the observation), raw_start, raw_end (as supplied), weight, instant, the strict left_observation_censored and right_observation_censored flags, and duration. session and the explicit onset_censored/terminus_censored flags are copied unchanged from the raw spell when the network carries them.

"vertex_spells": one row per maximal declared activity component, with vertex_spell, node, start, end, duration, instant, session, onset_censored and terminus_censored. Half-open positive spells and exact points are both representable. Undeclared vertices are implicitly always active and receive no synthetic rows, so this table is empty for a network with no declared vertex activity.

"nodes": one row per vertex, with name, any static attributes supplied at construction, and one column per measure named in measure.

"bins": one row per measurement window, with bin, lo, hi, time (the bin's representative time) and closed (whether the upper bound is included). Bins are component-qualified under discontinuous observation.

"network": one row per aggregate vertex pair, with from, to and the summed weight cograph renders.

Examples

dn <- dynet(school_contacts)
spells <- as.data.frame(dn)
head(spells)
as.data.frame(dn, what = "nodes")
as.data.frame(dn, what = "vertex_spells")

# Annotate the vertex table so it can be filtered without a second call.
busy <- as.data.frame(dn, what = "nodes",
                      measure = c("degree", "indegree", "outdegree"))
subset(busy, degree > 15)

Description

Coerce an animation to a data frame

Usage

## S3 method for class 'dynet_animation'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("bins", "frames"),
  ...
)

Arguments

Value

A plain data.frame.

Examples

if (requireNamespace("gifski", quietly = TRUE) &&
  requireNamespace("cograph", quietly = TRUE)) {
  dn <- dynet(school_contacts)
  frames <- animate(dn, step = 6, window = 6, tween = 2)
  as.data.frame(frames)
  as.data.frame(frames, what = "frames")
}

Description

Tidy tables from a collapsed temporal network

Usage

## S3 method for class 'dynet_collapsed'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("edges", "nodes"),
  ...
)

Arguments

Value

A plain data.frame. For "edges", one row per collapsed vertex pair carrying every weighting side by side: from, to, binary, union_duration, total_duration, duration_fraction, spell_count, weight_sum, weighted_duration, latest_weight, first, last, and the activity.duration and activity.count aliases. For "nodes", one row per vertex with name, any static vertex attributes the network carries, activity_duration and its activity.duration alias. See collapse_network() for what each weighting means.

Examples

dn <- dynet(school_contacts)
collapsed <- collapse_network(dn)
as.data.frame(collapsed)
as.data.frame(collapsed, what = "nodes")

Description

Stacks the per-session edge tables into one tidy frame with a session key, so a session-separated collapse reads like every other verb's result. Without this the base method flattened the list sideways into a single row of s1.from, s2.from, ... columns.

Usage

## S3 method for class 'dynet_collapsed_list'
as.data.frame(x, row.names = NULL, optional = FALSE, session = NULL, ...)

Arguments

Value

A plain data.frame, one row per collapsed pair per session, with session first and then the columns as.data.frame.dynet_collapsed() returns.

Examples

dn <- dynet(data.frame(
  from = c("A", "A"), to = c("B", "B"), start = c(0, 0), end = c(2, 3),
  session = c("s1", "s2")
), session = "session")
by_session <- collapse_network(dn, sessions = "separate")
as.data.frame(by_session)
as.data.frame(by_session, session = "s1")

Description

Tidy data frame of a temporal community partition

Usage

## S3 method for class 'dynet_communities'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("membership", "sizes", "runs", "events"),
  ...
)

Arguments

Value

A plain data frame.

Description

Tidy tables from an event graph

Usage

## S3 method for class 'dynet_event_graph'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("events", "adjacencies"),
  ...
)

Arguments

Value

A plain data frame; the columns are listed under event_graph().

Examples

dn <- dynet(school_contacts)
eg <- event_graph(dn, delta = 1)
as.data.frame(eg)
as.data.frame(eg, what = "adjacencies")

Description

Tidy data frame of a temporal measure

Usage

## S3 method for class 'dynet_metric'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  layout = c("long", "wide"),
  what = c("values", "diagnostics"),
  top = NULL,
  ...
)

Arguments

Value

A plain data.frame. Long layout carries measure and value with one row per observation, alongside whichever columns say what was measured: session when the network has sessions, time for anything measured on a grid of bins, node for a vertex-level quantity, from and to for a pair-level one, raw_spell for per-spell edge durations and vertex_spell with implicit for per-spell vertex durations from durations(), and from_group and to_group for mixing(). A graph-level series carries time, measure and value alone.

Wide layout puts the identifying columns first and spreads what varies across the rest. A measure taken on a grid of bins spreads time: one column per bin, named t followed by the bin's time, leaving one row per vertex and measure. A measure with no time axis, such as reachability, spreads the measures instead: one column per measure, leaving one row per vertex. A measure with no time axis and only one measure is already wide and comes back unchanged.

Examples

dn <- dynet(school_contacts)
degree <- centrality_series(dn, measure = "degree")
as.data.frame(degree)
as.data.frame(degree, layout = "wide")
as.data.frame(degree, top = 5)
as.data.frame(degree, what = "diagnostics")

Description

Tidy data frame of a multislice modularity result

Usage

## S3 method for class 'dynet_modularity'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("total", "bins"),
  ...
)

Arguments

Value

A plain data frame.

Description

Tidy frame of a temporal motif census

Usage

## S3 method for class 'dynet_motifs'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A plain data.frame carrying the same rows and columns as x: motif, family, pattern and count, preceded by node for a local census and by session when the census is session-local.

Description

Coerce surrogate networks to a data frame

Usage

## S3 method for class 'dynet_null'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A base data frame, one row per surrogate spell per replicate.

Description

Tidy tables from a temporal path-union network

Usage

## S3 method for class 'dynet_path_network'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("edges", "nodes"),
  ...
)

Arguments

Value

A plain data.frame. For "edges", one row per hop used by an optimal route, with from, to, weight, first_time, last_time and n_endpoints. For "nodes", one row per reached vertex, with name, arrival_time, latency, n_hops, n_paths and groups. See path_network() for what each column means.

Examples

dn <- dynet(school_contacts)
routes <- paths(dn, from = "Ana")
union_network <- path_network(routes)
as.data.frame(union_network, what = "edges")
as.data.frame(union_network, what = "nodes")

Description

Tidy table of a temporal trajectory tree

Usage

## S3 method for class 'dynet_path_trajectories'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A plain data frame with one row per tree node, with the columns described in path_trajectories() and none of its attributes.

Examples

dn <- dynet(school_contacts)
routes <- paths(dn, from = "Ana")
trajectories <- path_trajectories(routes)
as.data.frame(trajectories)

Description

Tidy data frame of time-respecting paths

Usage

## S3 method for class 'dynet_paths'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("paths", "steps"),
  ...
)

Arguments

Value

A plain data.frame. For "paths", one row per endpoint vertex, the source included, with the columns paths() documents: node, reachable, arrival_time, attained, latency, n_hops and n_paths, plus path_session and n_best_sessions under sessions = "bounded", and session and origin under sessions = "separate". For "steps", one row per step of every reconstructed optimal route, with endpoint (the vertex the route ends at), path_id (which of the tied optimal routes to that endpoint), path_session, step (position along the route, starting at the source), node (the vertex occupied at that step), time (when it was reached) and attained.

Examples

dn <- dynet(school_contacts)
reach <- paths(dn, from = "Ana")
as.data.frame(reach)
as.data.frame(reach, what = "steps")

Description

Tidy data frame of ranked pathways

Usage

## S3 method for class 'dynet_pathways'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("routes", "steps"),
  ...
)

Arguments

Value

A plain data.frame with the columns described in pathways(), most frequent first, or the per-step table when what = "steps".

Examples

dn <- dynet(school_contacts)
routes <- pathways(dn, from = "Ana")
as.data.frame(routes)
as.data.frame(routes, what = "steps")

Description

Tidy data frame of detected temporal phases

Usage

## S3 method for class 'dynet_phases'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("bins", "profile", "phases"),
  ...
)

Arguments

Value

A plain data frame.

Description

Tidy tables from a time-projected network

Usage

## S3 method for class 'dynet_projection'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("vertices", "edges"),
  ...
)

Arguments

Value

A plain data frame. Vertex rows contain state, optional session and observation, slice, time, start, end, closed, node, active, and copied node attributes. Edge rows contain from_state, to_state, from_node, to_node, optional session, from_slice, to_slice, from_time, to_time, edge_type, weight, n_spells, and lag.

Examples

dn <- dynet(school_contacts)
projected <- projection(dn, step = 4, window = 4)
as.data.frame(projected)
as.data.frame(projected, what = "edges")

Description

Tidy data frame of participation shift counts

Usage

## S3 method for class 'dynet_pshifts'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A plain data.frame carrying the same rows and columns as x. For a result built with output = "final" that is one row per shift type – shift, family and count – preceded by session when the result is session-local; the thirteen Gibson shift types are always present, including those with a count of zero. For output = "cumulative" it is thirteen rows per classified turn, adding sequence, event, time, speaker, target and group ahead of shift, family and count.

Examples

dn <- dynet(school_contacts)
shifts <- pshifts(dn)
as.data.frame(shifts)

Description

Coerce a permutation test to a data frame

Usage

## S3 method for class 'dynet_significance'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A base data frame, one row per tested cell.

Description

Tidy table of time-bin similarity

Usage

## S3 method for class 'dynet_similarity'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A plain data.frame, one row per ordered pair of time bins, with columns time, other, measure and value.

Examples

dn <- dynet(school_contacts)
resemblance <- similarity(dn, step = 4, window = 4)
as.data.frame(resemblance)

Description

Tidy table of snapshot edges

Usage

## S3 method for class 'dynet_snapshot'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A plain data.frame with the same rows and columns.

Examples

dn <- dynet(school_contacts)
bins <- snapshots(dn)
bins_table <- as.data.frame(bins)
head(bins_table)

Description

Tidy data frame of community trajectories

Usage

## S3 method for class 'dynet_trajectory'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("node", "time", "global", "allegiance"),
  ...
)

Arguments

Value

A plain data frame.

Description

Whether a vertex acts in bursts or at a steady pace. Burstiness compares the spread of the gaps between a vertex's events with their average: it approaches 1 for increasingly heterogeneous sequences, has theoretical reference value 0 for a Poisson process, and is -1 for a metronome. The memory coefficient asks a different question – whether a short gap tends to be followed by another short gap.

Two vertices can post the same number of times and differ entirely on both.

Usage

burstiness(
  dn,
  measure = c("burstiness", "memory", "events"),
  sessions = c("bounded", "collapse", "separate"),
  plot = FALSE
)

Arguments

Details

One raw spell row contributes its start time once to each distinct incident vertex. A self-loop is one event, equal-time rows remain distinct events, direction does not alter incidence, and interval ends and weights are ignored. Sorted equal times therefore create legitimate zero gaps. Explicitly onset-censored limits are not observed onset events and are excluded; terminus censoring does not affect this onset sequence.

If the usable interevent gaps are $\tau_1,\ldots,\tau_k$, burstiness is

$B=(\sigma-\mu)/(\sigma+\mu),$

where $\mu$ is their mean and $\sigma=\sqrt{k^{-1}\sum_i(\tau_i-\mu)^2}$ is the population standard deviation of the equal-mass empirical gap distribution. mean_gap needs at least one gap. Burstiness needs at least two and is NA if every usable gap is zero. Its finite-sample range is ⁠[-1, 1)⁠.

Memory is the ordinary Pearson correlation between consecutive gaps. It needs at least two adjacent-gap pairs and nonzero variation on both sides; otherwise it is NA. In sessions = "bounded", primitive gaps and adjacent pairs are formed within each session and then pooled, so no cross-session gap is introduced. Collapse includes calendar gaps after erasing labels; separate returns session-local blocks over the fixed vertex universe.

Value

A dynet_metric at node level with no time column: one row per vertex and measure. Attributes record the event identity, dispersion, memory, loop, weight, and session-gap conventions as event_identity = "incident_spell_start", dispersion = "population", memory = "lag1_pearson", loop_contribution = "one_event", weights = "ignored", and mode-specific session_gaps.

References

Goh, K.-I., & Barabasi, A.-L. (2008). Burstiness and memory in complex systems. Europhysics Letters, 81(4), 48002, equations 1 and 4. doi:10.1209/0295-5075/81/48002

Examples

dn <- dynet(school_contacts)
burstiness(dn)

Description

Centrality for every vertex at every time point. Ask for several measures in one call and they arrive stacked in a single tidy frame, one row per vertex, time point and measure.

Each value measures the network as it stands in one time bin, so the result is a trajectory of ordinary centrality. Order within a bin is not used: every tie active in the bin counts as present. Centrality computed from time-respecting paths across the whole period is path_centrality().

Usage

centrality_series(
  dn,
  measure = "degree",
  sessions = c("bounded", "collapse", "separate"),
  sample = NULL,
  damping = 0.85,
  mode = c("all", "out", "in"),
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  exponent = 1,
  prestige = "indegree",
  rescale = FALSE,
  lambda = 1,
  groups = NULL,
  plot = FALSE
)

Arguments

Details

step and window are separate on purpose. step is how often you look; window is how much of the timeline each look takes in. Setting them equal partitions the period; setting window larger than step is a rolling window, which keeps the resolution of the smaller step while smoothing over the noise of a sparse bin. The arguments match tsna::tSnaStats(), where they are called time.interval and aggregate.dur.

Snapshot "degree" counts distinct active binary dyads, so duplicate, split and overlapping spells do not multiply it; mode = "all" on a directed snapshot is in-degree plus out-degree. "strength" is the same margin taken over spell weights rather than over binary dyads. In a positive window each spell contributes its weight in proportion to the share of its duration that falls inside the window, weight * overlap / duration, so a spell straddling two tiled windows splits its weight between them and the pieces add back to the whole. A point contact has no duration to split and contributes its full weight to the window holding it. With window = 0 every active spell contributes its full weight at that instant. The share uses the spell's recorded duration, so the part of a spell outside the observation period is not reassigned to observed windows. snapshots() and the network plots keep full weights per bin, so their weight column is not the input to this strength.

Snapshot "closeness" is not Freeman's $1 / \sum_z d_{sz}$, which is undefined once a snapshot is disconnected – and a time bin almost always is. It is the reciprocal of the mean geodesic distance to the vertices a vertex can actually reach: with $R_s$ the reachable nonself set,

$C(s) = |R_s| / \sum_{z \in R_s} d_{sz},$

which is zero for an isolate and equals Freeman's normalised closeness $(n - 1) / \sum_z d_{sz}$ on a connected snapshot. "harary" is the reciprocal of eccentricity, zero for a vertex that cannot reach everything.

"eigenvector", "hub" and "authority" are certified the way eigenvector prestige is: a snapshot whose spectral radius is zero (no cycle) or whose Perron root is repeated (components of equal weight) has no single answer, and every vertex of that block is NA under a warning of class dynet_eigen_undefined. "eigenvector" is uniquely determined when the Perron eigenvalue has a one-dimensional eigenspace; strong connectivity is a sufficient condition. Disconnected snapshots with equally dominant components can have more than one correct eigenvector, so read the result as a within-snapshot ranking rather than an automatically comparable number across the whole series.

Indegree prestige is the column sum of the directed binary active-dyad adjacency matrix. It is exactly snapshot degree with mode = "in": duplicate, split, and overlapping spells and edge weights do not multiply the result, while an explicitly retained directed loop contributes once. With rescale = TRUE, the column sums are divided by their block total. A zero total is mathematically undefined and is returned as literal NaN.

Row-normalised indegree prestige first converts every nonzero binary adjacency row to sum one; zero rows remain all zero. Its column sums are the received sender-nomination mass, so their total is the number of active senders. rescale = TRUE divides again by that block total. This closed-form transform is the sna::prestige(cmode = "indegree.rownorm") definition on binary matrices. Dynet deliberately ignores edge weights, whereas sna uses their magnitudes on valued matrices.

Row-column-normalised prestige uses deterministic Sinkhorn–Knopp scaling only when the full binary vertex matrix has total support: every active dyad must belong to a perfect matching. It preserves all binary dyads and does not remove isolates or unsupported edges. Infeasible blocks return NA for every vertex with a classed warning. A feasible transform has every incoming column sum equal to one, so raw prestige is uniformly one and rescaled prestige uniformly 1 / n; this definition is a transform diagnostic, not a vertex ranking. Dynet uses fixed-order sweeps, maximum absolute row/column residual 1e-12, and at most 10,000 sweeps. It never returns a partial iterate. This deliberately differs from the randomised loose-tolerance annealer in sna 2.8.

Domain prestige is incoming indegree in the directed reachability graph after excluding its reflexive diagonal. If H[i,j] records whether i = j or a directed path from i to j exists, then p[j] = sum(H[,j]) - 1. Every distinct reaching vertex counts once, regardless of path length or multiplicity. Loops cannot add self credit, isolates score zero, and a zero-total rescaling returns literal NaN. Closure is computed on the binary active snapshot for each reporting block, not on chronologically ordered temporal journeys through the raw spells.

Domain-proximity prestige additionally uses the shortest incoming hop distances. For the nonself domain D[j], let r[j] be its size and s[j] the sum of its finite distances into j. The score is zero when r[j] = 0 and otherwise r[j]^2 / ((n - 1) * s[j]): the incoming domain fraction divided by mean hop distance. Unreachable vertices are omitted before the distance sum. This deliberately fixes an arithmetic artefact in sna 2.8, whose FALSE * Inf operation incorrectly zeros partial nonempty domains.

Eigenvector prestige solves t(B) %*% p = rho * p for the nonnegative Perron ray of binary adjacency B. It requires positive spectral radius and a one-dimensional Perron eigenspace. Raw scores have Euclidean norm one; rescale = TRUE makes their sum one. Zero-radius or nonunique blocks return all NA with a classed warning and diagnostics. Periodic cycles remain valid even when negative or complex roots share the spectral radius. Dynet uses direct eigenvalues plus an SVD nullity/residual check at tolerance 1e-10, orients the ray as nonnegative, and never applies elementwise absolute value.

Row-normalised eigenvector prestige first forms binary adjacency B and divides each nonzero sender row by its number of distinct outgoing dyads; zero rows remain exactly zero. It then solves the certified incoming Perron equation for the transpose of that row-stochastic matrix. Thus each active sender distributes one unit of recursive nomination mass, with no teleportation or dangling-row imputation. Binary session union and retained loop policy occur before row normalisation. The positive-radius, geometric- uniqueness, nonnegative-sign, L2/sum-scale, warning, and diagnostic rules are otherwise exactly those of ordinary eigenvector prestige.

Column-normalised eigenvector prestige divides each nonzero binary receiver column by its number of distinct incoming dyads; zero columns remain zero. It solves the incoming Perron equation only after that transform. If every vertex has positive indegree, the transformed transpose is row-stochastic and every certified score is necessarily uniform. Nonuniform defined scores therefore require a zero-indegree vertex. Binary union and retained-loop policy precede normalisation; certification and scaling remain those above.

Row-column-normalised eigenvector prestige composes the total-support and deterministic Sinkhorn–Knopp contract with the certified Perron contract. Infeasible support and nonconvergent balancing terminate before the spectral solve. A completed doubly stochastic transform always has the all-ones Perron ray, but reducible transforms have several such rays and remain undefined. Every fully certified score is therefore exactly uniform: 1 / sqrt(n) raw or 1 / n rescaled. This selector diagnoses support, balance, and irreducibility; it is not a vertex ranking.

Declared vertex activity induces the eligible vertex population before any kernel is evaluated. Positive windows independently use any-time vertex and edge unions before induction, while window = 0 evaluates the exact state. Results remain rectangular over the fixed vertex universe: inactive vertices receive typed NA, while eligible isolates keep the centrality kernel's ordinary static result.

Value

A dynet_metric: a tidy data frame with one row per vertex, time point and measure. Columns are session (only under sessions = "separate", which is the only mode that keeps session labels apart), time, node, measure and value. Print it, summary() it, plot() it, or take the plain frame with as.data.frame(). Prestige stores its mathematical choices as direct attributes for a prestige-only result and as named records under measure_metadata otherwise. When a prestige variant is structurally undefined or fails to converge, the affected values are NA, a warning says how many reporting blocks were affected, and a record naming the stage and reason for each comes out through as.data.frame(x, what = "diagnostics").

Conditions

Errors: dynet_unknown_measure (a measure not listed above), dynet_needs_directed ("prestige", "hub", "authority", "indegree" or "outdegree" on an undirected network), dynet_no_sessions (sessions = "separate" without a session column), dynet_outside_observation (the requested range misses observed support; it also carries dynet_bad_input), and dynet_bad_input for every other broken contract – dn not a dynet, an unknown mode, an out-of-range damping, exponent, lambda, prestige, rescale, start, end, step or window, and rescale = TRUE without measure = "prestige".

Warnings: dynet_deprecated (measure = "indegree"/"outdegree", or the retired sample argument), dynet_eigen_undefined and dynet_kernel_singular (both also carrying dynet_measure_undefined) when a snapshot's eigenvector, hub, authority, Bonacich power or information kernel has no unique answer, and dynet_prestige_infeasible, dynet_prestige_nonconvergence and dynet_prestige_eigen_undefined when a prestige variant is structurally undefined or fails to converge.

References

Holme, P., & Saramaki, J. (2012). Temporal networks. Physics Reports, 519(3), 97-125.

Wasserman, S., & Faust, K. (1994). Social Network Analysis: Methods and Applications. Cambridge University Press, Chapter 5.

Butts, C. T. (2024). sna: Tools for Social Network Analysis, version 2.8. doi:10.32614/CRAN.package.sna.

Lin, N. (1976). Foundations of Social Research. McGraw-Hill.

Freeman, L. C. (1979). Centrality in social networks: conceptual clarification. Social Networks, 1(3), 215-239. doi:10.1016/0378-8733(78)90021-7

Brandes, U. (2001). A faster algorithm for betweenness centrality. Journal of Mathematical Sociology, 25(2), 163-177.

Bonacich, P. (1987). Power and centrality: a family of measures. American Journal of Sociology, 92(5), 1170-1182.

Hage, P., & Harary, F. (1995). Eccentricity and centrality in networks. Social Networks, 17(1), 57-63.

Stephenson, K., & Zelen, M. (1989). Rethinking centrality. Social Networks, 11(1), 1-37.

Goh, K.-I., Kahng, B., & Kim, D. (2001). Universal behavior of load distribution in scale-free networks. Physical Review Letters, 87(27), 278701.

Freeman, L. C., Borgatti, S. P., & White, D. R. (1991). Centrality in valued graphs. Social Networks, 13(2), 141-154.

Page, L., Brin, S., Motwani, R., & Winograd, T. (1999). The PageRank citation ranking: bringing order to the web. Technical Report 1999-66, Stanford InfoLab.

Kleinberg, J. M. (1999). Authoritative sources in a hyperlinked environment. Journal of the ACM, 46(5), 604-632. doi:10.1145/324133.324140.

Seidman, S. B. (1983). Network structure and minimum degree. Social Networks, 5(3), 269-287. doi:10.1016/0378-8733(83)90028-X.

Burt, R. S. (1992). Structural Holes: The Social Structure of Competition. Harvard University Press.

Kundu, S., Murthy, C. A., & Pal, S. K. (2011). A new centrality measure for influence maximization in social networks. In Pattern Recognition and Machine Intelligence, Lecture Notes in Computer Science 6744 (pp. 242-247). Springer. doi:10.1007/978-3-642-21786-9_40.

Bonacich, P. (1972). Factoring and weighting approaches to status scores and clique identification. Journal of Mathematical Sociology, 2, 113-120. doi:10.1080/0022250X.1972.9989806.

Berman, A., & Plemmons, R. J. (1994). Nonnegative Matrices in the Mathematical Sciences. SIAM. doi:10.1137/1.9781611971262.

Sinkhorn, R. (1964). A relationship between arbitrary positive matrices and doubly stochastic matrices. Annals of Mathematical Statistics, 35, 876-879. doi:10.1214/aoms/1177703591.

Sinkhorn, R., & Knopp, P. (1967). Concerning nonnegative matrices and doubly stochastic matrices. Pacific Journal of Mathematics, 21, 343-348. doi:10.2140/pjm.1967.21.343.

Knight, P. A. (2008). The Sinkhorn-Knopp algorithm: convergence and applications. SIAM Journal on Matrix Analysis and Applications, 30, 261-275. doi:10.1137/060659624.

See Also

path_centrality() for closeness and betweenness on time-respecting paths; reachability() for temporal reach.

Examples

dn <- dynet(school_contacts)

centrality_series(dn, measure = "degree")
centrality_series(dn, measure = c("degree", "betweenness"))
centrality_series(dn, measure = "prestige", rescale = TRUE)
centrality_series(dn, measure = "prestige",
                  prestige = "indegree.rownorm")
centrality_series(dn, measure = "prestige", prestige = "domain")
centrality_series(dn, measure = "prestige",
                  prestige = "domain.proximity")
centrality_series(dn, measure = "prestige", prestige = "eigenvector")
centrality_series(dn, measure = "prestige",
                  prestige = "eigenvector.rownorm")
centrality_series(dn, measure = "prestige",
                  prestige = "eigenvector.colnorm")
centrality_series(dn, measure = "prestige",
                  prestige = "eigenvector.rowcolnorm")

# A seven-day window, stepped one day at a time.
centrality_series(dn, measure = "degree", step = 1, window = 7)

degree <- centrality_series(dn, measure = "degree")
summary(degree)

Description

Restore implicit observation support

Usage

clear_observations(dn)

Arguments

Value

A new dynet object, class c("dynet", "netobject", "cograph_network"), observed continuously from its earliest raw start through its latest raw end. Every explicit observation field is dropped from the metadata and the bin count is recomputed over the raw range; spells and attributes are untouched. Safe on a network that never had explicit observations, which is returned with only its recorded call changed.

Examples

dn <- dynet(school_contacts)
first_week <- set_observations(dn, start = 0, end = 7)
restored <- clear_observations(first_week)
restored

Description

Creates a static cograph network from the exact observed, endpoint-valid activity in a requested time range. Every collapsed edge retains all common duration summaries, so choosing one weighting does not discard the others.

Usage

collapse_network(
  dn,
  start = NULL,
  end = NULL,
  weight = c("binary", "union_duration", "total_duration", "duration_fraction",
    "spell_count", "weight_sum", "weighted_duration", "latest_weight"),
  sessions = c("bounded", "collapse", "separate"),
  censored = c("include", "exclude")
)

Arguments

Value

A dynet_collapsed cograph netobject, whose two tidy tables are reached with as.data.frame(x, what = "edges") and as.data.frame(x, what = "nodes"). With sessions = "separate", a named dynet_collapsed_list of such objects, one per session.

The edge table carries one row per collapsed pair and every weighting at once, so choosing one does not discard the others: from, to, binary (1 for a pair that was ever active), union_duration (time the pair was active, overlaps counted once), total_duration (summed spell lengths, overlaps counted twice), duration_fraction (union_duration over the pair's joint activity opportunity, NA when that opportunity is zero), spell_count, weight_sum, weighted_duration (weight times duration, summed), latest_weight (the weight of the last spell to end), first and last (the pair's earliest onset and latest terminus), and the activity.duration and activity.count aliases for compatibility with networkDynamic::network.collapse().

The node table carries one row per vertex, with name, any static vertex attributes the network was built with, activity_duration (time the vertex was active, overlaps counted once) and its activity.duration alias.

Examples

dn <- dynet(data.frame(
  from = c("A", "A"), to = c("B", "B"),
  start = c(0, 1), end = c(2, 3)
))
flat <- collapse_network(dn, weight = "union_duration")
as.data.frame(flat)

Description

"Who is with whom" and "did the structure reorganise, and when" are different questions. This one compares each bin's partition with another bin's by a label-invariant statistic, so it says how much changed without needing to know which community became which.

Because every statistic here is invariant to relabelling, match_communities() is not a prerequisite. That is a common misunderstanding and it is worth stating plainly: matching is needed to follow a community, not to measure change.

Usage

community_change(
  x,
  measure = c("nmi", "ami", "ari", "vi", "split_join", "jaccard", "omega_index", "uami",
    "iami"),
  against = c("previous", "first", "all")
)

Arguments

Details

Every statistic is built from the contingency table of the two labellings, restricted to the vertices active in both bins. A vertex that merely goes quiet must not read as a reorganisation, so it is dropped from both sides rather than counted as having left its community. When fewer than two vertices are shared, nothing is defined and the value is NA – a real absence, not a zero.

The first bin has no predecessor, so under against = "previous" its value is NA by construction.

What each measures, briefly. "nmi" is shared information normalised by the mean entropy, in $[0, 1]$, high for agreement; it is not chance-corrected, so two unrelated partitions score above zero. "ami" is the same quantity with the chance level subtracted, and is the one to reach for. "ari" is chance-corrected pair agreement, centred on zero for unrelated partitions. "vi" is a true metric in nats, zero for agreement and unbounded above. "split_join" counts the vertices that would have to move, so it is an integer in $[0, 2N]$. "jaccard" scores agreement over co-classified pairs. "omega_index" is chance-corrected pair agreement; for the disjoint partitions this package produces it coincides exactly with "ari", and it is offered because it is what multinet reports and because it generalises to overlapping communities.

"uami" and "iami" are Zhong et al.'s (2025) answer to a problem every temporal network has: the vertex set moves between bins, and ordinary mutual information assumes it does not. "iami" compares over the intersection, the vertices both bins have. "uami" compares over the union, giving each partition one extra virtual community holding the vertices it does not have, so a vertex arriving or leaving is itself information about the change rather than something discarded. The two answer different questions: "iami" asks whether the vertices that stayed kept their company, "uami" asks whether the whole structure held. Since every other measure here is already restricted to the shared vertices, "iami" is numerically identical to "ami" in this package, and is offered under both names because the literature uses both.

Two notes on the sources, because both cost time to discover. Adjusted mutual information admits more than one normaliser: this package divides by the arithmetic mean of the two entropies, matching "nmi" above, sklearn's default, and the stated intent of Zhong et al.; aricode::AMI divides by the maximum instead, so the two disagree by convention and not by error. And the expression printed for the adjusted measures in Zhong et al. subtracts the chance term once in a denominator that needs it twice, which scores two identical partitions at 0.949 rather than 1; the corrected form is used here.

Value

A dynet_metric at graph level. For "previous" and "first", one row per bin per measure with columns session, time, measure, value; for "all", one row per ordered pair with an other column giving the bin compared against, in the same long shape similarity() uses so both plot with the same code. The n_compared attribute records how many vertices each comparison could actually use.

References

Danon, L., Diaz-Guilera, A., Duch, J., & Arenas, A. (2005). Comparing community structure identification. Journal of Statistical Mechanics, P09008.

Hubert, L., & Arabie, P. (1985). Comparing partitions. Journal of Classification, 2, 193-218.

Meila, M. (2007). Comparing clusterings – an information based distance. Journal of Multivariate Analysis, 98(5), 873-895.

van Dongen, S. (2000). Performance criteria for graph clustering and Markov cluster experiments. CWI Technical Report INS-R0012.

Collins, L. M., & Dent, C. W. (1988). Omega: a general formulation of the Rand index of cluster recovery suitable for non-disjoint solutions. Multivariate Behavioral Research, 23(2), 231-242.

Gates, A. J., & Ahn, Y.-Y. (2019). Element-centric clustering comparison unifies overlaps and hierarchy. Scientific Reports, 9, 8574.

Vinh, N. X., Epps, J., & Bailey, J. (2010). Information theoretic measures for clusterings comparison. JMLR, 11, 2837-2854.

Zhong, P., Ba, C., Mondragon, R., & Clegg, R. (2025). Quantifying community evolution in temporal networks. Scientific Reports, 15, 45373.

Examples

dn <- dynet(school_contacts)
found <- temporal_communities(dn, step = 5, window = 5, seeds = 1:5)
community_change(found)
community_change(found, measure = c("ami", "ari"))
community_change(found, measure = c("iami", "uami"))

Description

Once labels mean the same thing in every bin, the interesting quantities are about vertices rather than communities: how often one changes group, how many groups it has belonged to, how reliably it stays put, how often two vertices are found together, and how tightly a vertex sticks to its own reference group rather than visiting others.

Usage

community_trajectory(
  x,
  measure = c("flexibility", "promiscuity", "persistence"),
  reference = NULL
)

Arguments

Details

Let $C_{it}$ be the community of vertex $i$ in bin $t$, over $T$ bins.

Flexibility is the share of consecutive bins in which a vertex changed community, $\frac{1}{T-1}\sum_{t=2}^{T}[C_{it} \ne C_{i,t-1}]$.

Promiscuity is how much of the whole community structure a vertex visited: its distinct-label count minus one, over the global distinct-label count minus one. A vertex that never moves scores zero; one that visits every community scores one. The denominator is global, not per vertex; that is teneto's convention and it is what makes the measure comparable across vertices.

Persistence is the complement of flexibility, and comes at three granularities: per vertex, per bin, and one number for the whole series. The per-bin form is NA in the first bin, which has no predecessor.

Allegiance $P_{ij} = \frac{1}{T}\sum_t [C_{it} = C_{jt}]$ is how often two vertices were in the same community. It divides by the number of bins, not by the bins in which both were active – teneto's convention, replicated here so the numbers agree.

Recruitment is a vertex's mean allegiance to the other members of its own reference group; integration is its mean allegiance to vertices outside it.

Why the labels must be matched first. All of these read a change of label as a change of group. If the labels are per-bin arbitrary – which they are whenever the slices were solved independently – then flexibility measures relabelling noise and nothing else. This verb therefore refuses to run on an unmatched partition rather than returning a number that looks fine.

Inactive vertices. A vertex inactive in a bin still carries the label its identity arc brought it, matching projection()'s waiting convention, so it is neither dropped nor treated as having left. n_inactive_states records how many states that covers, so the reader can judge.

Value

A dynet_metric at node level, one row per vertex per measure, with columns session (only when the network has sessions), node, measure and value. Every measure here summarises the whole series, so there is no time column; the per-bin and whole-series forms of persistence, and the pairwise allegiance table, are reached by as.data.frame(x, what = ).

References

Bassett, D. S., Wymbs, N. F., Porter, M. A., Mucha, P. J., Carlson, J. M., & Grafton, S. T. (2011). Dynamic reconfiguration of human brain networks during learning. PNAS, 108(18), 7641-7646.

Papadopoulos, L., Puckett, J. G., Daniels, K. E., & Bassett, D. S. (2016). Evolution of network architecture in a granular material under compression. Physical Review E, 94(3), 032908.

Bassett, D. S., Porter, M. A., Wymbs, N. F., Grafton, S. T., Carlson, J. M., & Mucha, P. J. (2013). Robust detection of dynamic community structure in networks. Chaos, 23(1), 013142.

Bassett, D. S., Yang, M., Wymbs, N. F., & Grafton, S. T. (2015). Learning-induced autonomy of sensorimotor systems. Nature Neuroscience, 18(5), 744-751.

Thompson, W. H., Brantefors, P., & Fransson, P. (2017). From static to temporal network theory. Network Neuroscience, 1(2), 69-99.

Examples

dn <- dynet(school_contacts)
found <- temporal_communities(dn, step = 5, window = 5, seeds = 1:5)
community_trajectory(found)
as.data.frame(community_trajectory(found), what = "time")

Description

Pair unit returns one row per vertex pair and measure, summarising every retained raw spell they shared. Spell unit returns each retained raw edge identity. Vertex-activity unit returns fixed-universe vertex summaries; vertex-spell unit returns canonical vertex-activity components. Duration is what separates an interval network from a contact network: a pair that met fifty times briefly and a pair that met once at length have the same edge weight in a static network and nothing else in common.

Usage

durations(
  dn,
  measure = c("events", "total", "mean"),
  sessions = c("bounded", "collapse", "separate"),
  censored = c("include", "exclude"),
  unit = c("pair", "spell", "vertex_activity", "vertex_spell", "node_ties"),
  mode = c("out", "in", "all"),
  plot = FALSE
)

Arguments

Details

Positive spell duration is the observed time during which both endpoints are eligible. Genuine eligible point contacts are retained with duration zero. Pair total sums these raw-spell durations, so overlapping identities intentionally multiply time; pair union counts binary calendar occupancy once. Consequently union <= total, and union cannot exceed the pair's eligible opportunity time. Pair events counts retained raw identities. Formally, if retained raw spell i has endpoint-valid fragments F[i], then ⁠duration[i] = sum((b - a) for [a,b) in F[i])⁠. For pair p, total[p] = sum(duration[i]), while union[p] is the Lebesgue measure of the calendar union of every positive fragment belonging to p. Point contacts therefore count as events and spells but contribute zero duration. These conventions follow the spell and dyad distinction in tsna::edgeDuration() (Butts, 2024, doi:10.32614/CRAN.package.tsna), with Dynet additionally applying its observation and endpoint-eligibility contract.

Collapse erases edge and vertex session labels before gating. Bounded gates within each session and then pools spell identities while unioning overlapping pair occupancy once on the shared calendar. Separate returns local blocks. Weights and vertex censor flags do not affect durations. Excluding raw edge censoring removes the whole identity, never only an observed fragment.

For a retained canonical vertex component k, let S[k] be its observed support, d[k] its total positive width, and f[k] and l[k] its extrema. Vertex total is sum(d[k]), while union is the measure of the calendar union of every positive S[k]; therefore ⁠0 <= union <= total⁠. Points count as identities with zero duration. A declared vertex with no retained support has zero events/total/union and missing mean/median/first/last. A wholly undeclared vertex has one measurement-only implicit always-active identity over observed support. This is stream-graph node presence duration as in Latapy, Viard, and Magnien (2018), doi:10.1007/s13278-018-0537-7, and agrees with tsna::vertexDuration() only under matching continuous-observation, non-session conventions.

Node-ties uses the same endpoint-valid raw spell supports as pair/spell duration. Directed out credits the tail, in credits the head, and all adds both endpoint stubs. A retained loop therefore contributes once to out, once to in, and twice to additive all-mode events/total; undirected results use the same two-stub rule. In contrast, node-tie union Boolean-unions all positive incident fragments, so loops, reciprocal overlap, duplicate rows, and simultaneous neighbours occupy calendar time only once. Consequently union <= total, and directed all equals out plus in only for events and total. Formally, for endpoint-stub multiplicity c[v,i,m], retained raw identity duration d[i], and positive support F[i], node-tie events are sum(c[v,i,m]), total is sum(c[v,i,m] * d[i]), and union is the measure of the calendar union of all F[i] having positive multiplicity. These union values cannot exceed the corresponding eligible vertex-activity union. Isolates, inactive vertices, and loopless singletons receive exact zeros for every node-tie measure. The additive quantities match tsna::tiedDuration() only for continuous observation, static eligible endpoints, uncensored matched spells, and no sessions; tsna is not an oracle for union, gaps/points, endpoint schedules, source censor filtering, or session policies (Bender-deMoll and Morris, 2025, doi:10.32614/CRAN.package.tsna).

Value

A dynet_metric. Pair and edge-spell units are edge-level: pair has columns from, to, measure, and value, while spell additionally has raw_spell. Administrative observation and endpoint-activity fragments are recombined by raw spell before the censored policy is applied. Vertex-activity unit has node, measure, and value; vertex-spell additionally has vertex_spell and implicit; both vertex units are node-level metrics. Node-ties is also node-level and has the fixed schema node, measure, and value (plus session only for separate mode).

Examples

dn <- dynet(school_contacts)
durations(dn)
durations(dn, measure = "union")
durations(dn, unit = "spell", measure = "duration")
durations(dn, unit = "vertex_activity")
durations(dn, unit = "vertex_spell")
durations(dn, unit = "node_ties", mode = "all")
tie_durations <- durations(dn)
summary(tie_durations, by = "measure")

Description

Builds a temporal network from a relational log. One constructor covers the four shapes relational data actually arrives in, and the shape is inferred from the arguments you name:

interval

Each row is an edge active over ⁠[start, end)⁠. Used when the data carry an end time or a duration.

contact

Each row is an instantaneous event with a time and no duration – a message, a click, a citation.

threaded

Forum, chat or email data. An edge is treated as active from its own post until the last post in the same thread, following Saqr and Nouri (2020). Name the thread argument to select this.

copresence

Two-mode attendance data. Actors sharing a group become connected for the span of that group. Name actor and group.

turns

A log of who acted when, with no recipient, such as coded chat or collaboration actions. Within each group, every action takes up the one before it: a directed contact from the previous actor to the current one, at the current action's time. Name actor, time and (optionally) group, and set format = "turns".

broadcast

The same kind of log, read as every action being addressed to the whole group: a directed contact from the actor to every other member of the group (every actor with an action in it), at the action's time. Name actor, group and time, and set format = "broadcast". event_graph(events = "messages") then treats each action as one event.

Every other column of data is kept as a tie attribute: it appears in as.data.frame() and can be selected on with induce_subgraph(ties = ). The exceptions are the canonical spell fields themselves – duration, weight, session, thread, onset_censored and terminus_censored – which are dropped even when they were never named as arguments, because the spell table owns those names. A non-atomic column raises dynet_bad_tie_attribute, and a factor is carried as character. Co-presence logs keep none, because their rows are memberships rather than ties.

Column names are resolved case-insensitively from a table of aliases, so Sender/Receiver, source/target and onset/terminus are all understood without being spelled out. Times may be numeric, Date, POSIXct or character date-time strings; character and date-time input is converted to elapsed time since the first event in a readable unit.

Vertices are addressed by name everywhere in this package. Integer vertex indices are used internally for speed but are never part of any result.

Explicit observation bounds are administrative measurement limits, not a destructive filter. A positive spell ⁠[s,e)⁠ contributes the half-open intersection ⁠[max(s,L),min(e,U))⁠ when it has positive duration, while a genuine instantaneous event is retained at either L or U. Original endpoints remain the only formation and dissolution events, censoring is never inferred from equality with a limit, and temporal paths must both start and finish inside the declared interval.

Vertex activity is a separate declaration. A vertex with at least one row in vertex_spells is eligible only on the union of those half-open positive spells and exact points; a vertex with no row remains eligible at all times. Snapshot measurements independently union eligible vertices and active edges over each positive window and then induce on eligible endpoints; point snapshots evaluate both at the exact time. Explicit vertex censor flags describe raw outer-boundary state and are never inferred from observation limits or used to alter eligibility.

Usage

dynet(
  data,
  from = NULL,
  to = NULL,
  start = NULL,
  end = NULL,
  duration = NULL,
  time = NULL,
  thread = NULL,
  actor = NULL,
  group = NULL,
  session = NULL,
  weight = NULL,
  nodes = NULL,
  groups = NULL,
  format = c("auto", "interval", "contact", "threaded", "copresence", "turns",
    "broadcast"),
  thread_clock = c("absolute", "relative"),
  directed = TRUE,
  interval = 1,
  time_unit = "auto",
  observation_start = NULL,
  observation_end = NULL,
  observation_spells = NULL,
  loops = FALSE,
  min_thread_posts = 1L,
  onset_censored = NULL,
  terminus_censored = NULL,
  vertex_spells = NULL
)

Arguments

Value

An object of class c("dynet", "netobject", "cograph_network"). It is a cograph network, so cograph::splot() draws it directly and every cograph rendering argument applies. Use as.data.frame() for the tidy spell table, as.data.frame(x, what = "nodes") for the vertex table, as.data.frame(x, what = "network") for the aggregate edge list, summary() for the description and plot() for a picture. Nothing in this package requires you to reach into the object.

References

Saqr, M., & Nouri, J. (2020). High resolution temporal network analysis to understand and improve collaborative learning. Proceedings of the Tenth International Conference on Learning Analytics & Knowledge, 314-319.

Holme, P., & Saramaki, J. (2012). Temporal networks. Physics Reports, 519(3), 97-125.

Butts, C. T. (2008). network: a package for managing relational data in R. Journal of Statistical Software, 24(2), 1-36.

Examples

# An interval log: each row carries its own start and end
dynet(school_contacts)

# A threaded log: edge stays active until its thread falls silent
dynet(forum_posts, thread = "thread")

# A co-presence log: actors sharing a group become connected
dynet(seminar_attendance, actor = "student", group = "seminar")

# A turns log: each action takes up the one before it in its group
chat <- data.frame(
  student = c("Ana", "Ben", "Ana", "Cy", "Dee", "Eli"),
  team = c("t1", "t1", "t1", "t1", "t2", "t2"),
  minute = c(1, 2, 4, 5, 1, 3),
  action = c("plan", "monitor", "discuss", "plan", "plan", "adapt")
)
dynet(chat, actor = "student", group = "team", time = "minute",
      format = "turns")

# The same log as broadcasts: each action reaches the whole team
dynet(chat, actor = "student", group = "team", time = "minute",
      format = "broadcast")

# Declare observation time without rewriting the source spell.
bounded <- dynet(data.frame(
  from = "A", to = "B", start = -2, end = 8
), observation_start = 0, observation_end = 5)
as.data.frame(bounded)

# Declare changing vertex eligibility without altering edge spells.
scheduled <- dynet(data.frame(
  from = "A", to = "B", start = 0, end = 10
), vertex_spells = data.frame(
  node = c("A", "A"), start = c(0, 7), end = c(4, 10)
))
as.data.frame(scheduled, what = "vertex_spells")

Description

Credits every optimal time-respecting journey to the contacts that carried it, giving a betweenness score per contact rather than per vertex. This is the measure intervention questions actually ask: not which people matter, but which meetings did.

The row unit is one canonical contact, not one pair. The same A -> B pair active in two disjoint spells is two rows, because a journey uses one of them and not the other.

Usage

edge_centrality(
  dn,
  measure = "betweenness",
  criterion = c("foremost_then_shortest", "min_hops", "foremost", "fastest"),
  sessions = c("bounded", "collapse", "separate"),
  start = NULL,
  end = NULL,
  traversal_time = 0
)

Arguments

Details

The score is not normalised, and its range is the same ⁠[0, (n-1)(n-2)]⁠ as the vertex measure.

An exact identity ties this to path_centrality(): because every optimal journey is vertex-simple, it enters each vertex through exactly one contact, so the scores of the contacts arriving at a vertex sum to that vertex's temporal betweenness plus the number of sources that reach it. The tests assert it, which makes this verb checkable without any external reference.

Value

A dynet_metric at edge level, one row per contact, with columns from, to, start, end, measure and value. A contact used by no optimal journey is present with value zero rather than dropped, so the result is a complete census.

References

Oettershagen, L., and Mutzel, P. (2022). TGLib: an open-source library for temporal graph analysis. ICDM Workshops. arXiv:2209.12587.

Brandes, U. (2001). A faster algorithm for betweenness centrality. Journal of Mathematical Sociology, 25(2), 163-177.

See Also

path_centrality() for the vertex form.

Examples

dn <- dynet(school_contacts)
edge_centrality(dn)

Description

Builds the event graph: every spell becomes a vertex, and an arc joins two events that share a vertex and follow one another in time there. A directed path in it is a time-respecting chain of events, so questions about temporal reachability, waiting times and cascades become questions about an ordinary static directed acyclic graph. It needs no time grid. The time-expanded graph of projection() is the other static representation; it has one vertex per vertex and time slice instead.

Usage

event_graph(
  dn,
  sessions = c("bounded", "collapse", "separate"),
  delta = Inf,
  adjacency = c("all", "next"),
  direction = c("respect", "ignore"),
  loops = FALSE,
  events = c("ties", "messages")
)

Arguments

Details

Events are ordered by start, then end, from and to, and numbered in that order. Event e1 precedes e2 at a shared vertex v when e2 starts strictly after e1 ends, and no more than delta later. An event therefore occupies its whole spell, as in the event graphs of Kivela et al. (2018): something carried by it is available at its endpoints once it has ended. Because the later event must start strictly after, two instantaneous events at the same instant are never adjacent, nor is an event that starts at the very instant another ends; every wait is positive, the graph is acyclic, and numbering events by start is a topological order. This is the rule of Reticula (Badie-Modiri and Kivela, 2023), the reference implementation of the construct.

Two events that share both endpoints are joined once per shared vertex, so they produce two adjacency rows with different via. This is correct: each row is a different way the second event can follow the first.

With adjacency = "all" every arc is an admissible hop and every chain of admissible hops is a path, so a path from an event leaving u to an event arriving at w exists exactly when w can be reached from u through events taken one after another. On contact data (instantaneous events), that is the reachability of paths() with a traversal_time shorter than the smallest gap between distinct contact times. It is not the reachability of paths() on interval spells, which may be entered at any instant while they are active rather than only as a whole. "next" keeps the earliest successors only, the consecutive-event adjacency of Kovanen et al. (2011) used for temporal motifs. It is much sparser, and with delta = Inf on an undirected network of instantaneous contacts it reaches the same events as "all". Otherwise it can lose reachability: on a directed network the earliest departure from a vertex need not lead where a later one does, and with interval spells the earliest successor can end after a later one has started.

No R package computes this construct, so it is checked against Dynet's own path search and against direct enumeration of event pairs.

Value

An object of class dynet_event_graph. Take its tables with as.data.frame(x) for the events, one row per spell (or per message), with event, session (under sessions = "separate"), from, to (for a message, its targets joined by commas), n_targets (messages only), start, end, duration, weight, spell (the spell the event came from, or a message's first spell, numbered in the order dynet() built them) and the tie attributes of that spell, except one whose name is already among these columns; and as.data.frame(x, what = "adjacencies") for the arcs, one row per pair of events and shared vertex, with from_event, to_event (the numbers of the two events in the event table), via (the shared vertex), first and second (the two events written as from->to, or from--to on an undirected network; a message to several targets as ⁠from->9 targets⁠), from_time (when the earlier event ends), to_time (when the later one starts), wait, under sessions = "separate" session, and each tie attribute of the two events as ⁠first_<name>⁠ and ⁠second_<name>⁠. summary() gives one row per event and plot() draws the graph.

Conditions

Errors: dynet_bad_input for a dn that is not a dynet, a delta that is not one non-negative number, or a loops that is not one logical value; dynet_no_sessions for sessions = "separate" without a session column; dynet_empty_network when no spell remains once self-loops are dropped.

References

Kivela, M., Cambe, J., Saramaki, J., & Karsai, M. (2018). Mapping temporal- network percolation to weighted, static event graphs. Scientific Reports, 8, 12357. doi:10.1038/s41598-018-29577-2

Mellor, A. (2018). The temporal event graph. Journal of Complex Networks, 6(4), 639-659. doi:10.1093/comnet/cnx048

Badie-Modiri, A., & Kivela, M. (2023). Reticula: A temporal network and hypergraph analysis software package. SoftwareX, 21, 101301. doi:10.1016/j.softx.2022.101301

Kovanen, L., Karsai, M., Kaski, K., Kertesz, J., & Saramaki, J. (2011). Temporal motifs in time-dependent networks. Journal of Statistical Mechanics: Theory and Experiment, P11005. doi:10.1088/1742-5468/2011/11/P11005

See Also

projection() for the time-expanded graph, paths() for time-respecting paths between vertices.

Examples

dn <- dynet(school_contacts)
eg <- event_graph(dn, delta = 1)
eg
as.data.frame(eg, what = "adjacencies")
summary(eg)

# Only the earliest successors, as for temporal motifs
sparse <- event_graph(dn, delta = 1, adjacency = "next")
sparse

Description

When relationships are born and when they die. In a static network every edge is present at once; here the turnover itself is the finding. A course typically shows formation front-loaded and dissolution piling up at the end, and a group that never dissolves an edge is behaving differently from one that constantly re-forms them.

Usage

events(
  dn,
  measure = c("formation", "dissolution"),
  sessions = c("bounded", "collapse", "separate"),
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  plot = FALSE
)

Arguments

Details

Formation and dissolution are counted inside each window, so overlapping windows (window > step) count the same event more than once by design – that is what a rolling total is. Setting window equal to step, the default, gives disjoint counts that sum to the total turnover. Explicitly onset-censored raw limits are not formations, and explicitly terminus-censored limits are not dissolutions. A left-censored observed tie is prior evidence for new_pairs; raw censor state never changes activity.

Formation fraction is defined only with window = 0. For a positive half-open interval ⁠[s,e)⁠, its pre-batch state at t is ⁠s < t <= e⁠ and its post-batch state is ⁠s <= t < e⁠. These predicates are binary-unioned per nonloop ordered pair or undirected dyad after the entire timestamp batch. Points are absent on both sides. A pair enters risk only when observation and both endpoints are eligible immediately before and after t and the pair is inactive before. A formation is confirmed when it is active after and at least one contributing positive raw spell has a known onset at t. The ratio is in ⁠[0,1]⁠; zero risk returns NA.

Duplicate, overlapping, or adjacent raw spells cannot multiply pair-state transitions. Observation and vertex boundaries are excluded by two-sided eligibility. Onset censoring suppresses confirmation but not state; terminus censoring, weights, loops, and point contacts do not contribute. Collapse erases labels, bounded authorises within sessions before unioning each calendar pair, and separate returns session-local fractions.

Dissolution fraction is the dual exact-time quantity. For each nonloop pair, let ⁠E-⁠ and ⁠E+⁠ be binary-union state on the symbolic one-sided limits and let L mean at least one positive raw spell ends exactly at the timestamp with a known terminus. The numerator is ⁠Z * E- * (1 - E+) * L⁠, where Z requires two-sided observation and endpoint eligibility; the denominator is ⁠sum(Z * E-)⁠, including pairs that remain active. Zero risk returns NA_real_, while positive risk with no confirmed dissolution returns zero. Censor flags do not change state: one known terminus confirms a disappearance but an all-censored disappearance is unconfirmed. Duplicate, overlapping, adjacent, and tied rows are unioned; points, loops, weights, onset censoring, and administrative observation/activity boundaries do not create transitions. Collapse erases labels, bounded unions authorised session-local states, and separate reports local rows. Positive windows are rejected because "dissolution_rate" owns dissolution rates.

Dissolution rate is the active-risk dual over a positive window. Its numerator sums confirmed binary pair dissolutions at included timestamp batches; its denominator integrates exact eligible active nonloop pair-time over observation, vertex, edge, and window change cells. Right-censored termini retain state and exposure but do not confirm an event, while one known duplicate suffices. Zero active exposure returns NA_real_; positive exposure without a confirmed dissolution is zero. The unit is inverse network time. It is not raw terminus intensity, spell-duration sum, or an average of instantaneous fractions; positive windows are required, and this is the rate "dissolution_rate" reports.

Formation rate is the positive-window counterpart. Its numerator sums the confirmed binary pair formations at each included timestamp, while its denominator integrates exact inactive eligible nonloop pair-time over change-point cells cut by the window, observation components, vertex activity, and edge state. It is not an average of instantaneous fractions, a raw-onset intensity, or an ever-observed-pair quantity. Zero exposure returns NA_real_; positive exposure with no confirmed formation returns zero. The unit is inverse network time and scales inversely with positive time scaling. Points have zero exposure, onset censoring suppresses only confirmation, and gap/boundary, duplicate, overlap, adjacency, loop, weight, and session rules follow the same ledger as "formation_fraction". window = 0 is rejected because that measure owns the instantaneous fractions.

Value

A dynet_metric at graph level, one row per time point and measure.

References

Andersen, P. K., & Gill, R. D. (1982). Cox's regression model for counting processes: a large sample study. Annals of Statistics, 10, 1100-1120. doi:10.1214/aos/1176345976

Butts, C. T., Leslie-Cook, A., Krivitsky, P. N., & Bender-deMoll, S. (2024). networkDynamic: Dynamic Extensions for Network Objects, version 0.11.5. doi:10.32614/CRAN.package.networkDynamic

Examples

dn <- dynet(school_contacts)
events(dn)
turnover <- events(dn, measure = c("formation", "dissolution"))
plot(turnover)
events(dn, measure = "formation_fraction", start = 1, end = 1,
           window = 0)
events(dn, measure = "dissolution_fraction", start = 1, end = 1,
           window = 0)
events(dn, measure = "formation_rate", start = 1, end = 2,
           window = 1)
events(dn, measure = "dissolution_rate", start = 1, end = 2,
           window = 1)

Description

Vertex attributes for forum_posts. Passed to dynet() through its nodes argument, these become available to mixing().

Usage

forum_people

Format

A data.frame with 20 rows and 3 columns:

name

Character. Matches the sender and receiver names in forum_posts.

role

Character. "Student" (16), "Teacher" (3) or "Facilitator" (1).

achievement

Character. "High", "Middle" or "Low" for students; NA for the four staff.

Source

Simulated, not observed. Generated deterministically under a fixed seed by data-raw/make-data.R.

Examples

dn <- dynet(forum_posts, thread = "thread", nodes = forum_people)
mixing(dn, attribute = "role")

Description

Posts in a course discussion forum over roughly eight weeks. Each row is one post directed at an earlier poster in the same thread. Because a post has a timestamp but no end, the duration of the tie has to be derived: dynet() treats a post as active until the last post in its thread, so a message that provoked a long argument stays live longer than one that fell flat.

Usage

forum_posts

Format

A data.frame with 241 rows and 4 columns:

sender

Character. Who wrote the post.

receiver

Character. Who the post replied to.

timestamp

POSIXct (UTC). When the post was made. Posts run from 2024-09-02 to 2024-10-27, just under eight weeks.

thread

Character. The discussion thread it belongs to; 62 threads.

Details

Pairs with forum_people, which carries the roles used for mixing analysis.

Source

Simulated, not observed. Generated deterministically under a fixed seed by data-raw/make-data.R.

Examples

dynet(forum_posts, thread = "thread", nodes = forum_people)

Description

Every interval between one event and the next, as a tidy table with one row per gap. burstiness() computes these gaps to reach B and M and then reports only their mean; this returns the distribution itself, so it can be plotted, fitted, or tested against a Poisson null.

Usage

gaps(
  dn,
  unit = c("node", "pair"),
  sessions = c("bounded", "collapse", "separate"),
  censored = c("exclude", "include"),
  plot = FALSE
)

Arguments

Details

A gap of exactly zero is legitimate and is kept: it is the signature of two distinct raw spells incident to the same vertex at one instant. Dropping those would silently raise the mean above the "mean_gap" that burstiness() reports from the same numbers.

Value

A dynet_metric data frame with one row per gap and no aggregation, level = "node" under unit = "node" and level = "edge" under unit = "pair". Columns are time, the onset of the later event of the pair, so the row sits at the moment the gap closed; node, or from and to under unit = "pair"; index, the 1-based rank of the gap within that vertex's or pair's ordered sequence, restarting at one in each session under "bounded" and "separate"; measure, the constant "gap"; and value, the gap in the network's time unit. A leading session column is present under sessions = "separate". A vertex or pair with fewer than two usable events contributes no rows rather than a missing one. Print it, summary() it, plot() it, or take the plain frame with as.data.frame().

Conditions

Errors: dynet_bad_input when dn is not a dynet, and dynet_no_sessions when sessions = "separate" is asked of a network with no session column. An unmatched unit, sessions or censored is rejected by match.arg() and is a plain error, not a classed one.

References

Goh, K.-I., & Barabasi, A.-L. (2008). Burstiness and memory in complex systems. Europhysics Letters, 81(4), 48002. doi:10.1209/0295-5075/81/48002

Karsai, M., Kaski, K., Barabasi, A.-L., & Kertesz, J. (2012). Universal features of correlated bursty behaviour. Scientific Reports, 2, 397. doi:10.1038/srep00397

Holme, P., & Saramaki, J. (2012). Temporal networks. Physics Reports, 519(3), 97-125. doi:10.1016/j.physrep.2012.03.001

See Also

burstiness() for the summary statistics of these gaps, and durations() for how long a tie was up rather than how long a pair was quiet.

Examples

dn <- dynet(school_contacts)
quiet <- gaps(dn)
quiet
summary(quiet)

dyads <- gaps(dn, unit = "pair")
dyads

Description

Truncates the rows without rewriting what the measure is. The printed header still describes the series the rows came from, and a ⁠first n of N rows⁠ line records the truncation.

Usage

## S3 method for class 'dynet_metric'
head(x, n = 6L, ...)

Arguments

Value

A dynet_metric with at most n rows, carrying the source counts so its header stays true to the series.

Examples

dn <- dynet(school_contacts)
degree <- centrality_series(dn, step = 4, window = 4)
head(degree)

Description

Extract an induced temporal subgraph

Usage

induce_subgraph(dn, nodes = NULL, ties = NULL, keep_isolates = FALSE)

Arguments

Value

A new dynet object, class c("dynet", "netobject", "cograph_network"), carrying only the selected spells, the vertices they touch (plus any isolate named in nodes when keep_isolates = TRUE), those vertices' activity spells, and all static node and tie attributes. Metadata is rebuilt, so the observed range and the canonical spell identifiers describe the subgraph, not the parent. Raises dynet_unknown_node for a name that is not a vertex, dynet_empty_network when the selection leaves no vertex or no tie, and dynet_bad_input when neither nodes nor ties is supplied or a selection is malformed.

Examples

dn <- dynet(school_contacts)

# A condition on the vertex table, in one call.
induce_subgraph(dn, degree > 16)

# Names still work, as does anything carrying them.
induce_subgraph(dn, nodes = c("Ana", "Ben", "Cara"))

Description

A community label is arbitrary within a bin. If bin 3's "community 2" is bin 4's "community 1", then flexibility, persistence and allegiance measure relabelling noise and nothing else. This verb walks the bins in order and gives a community the label of whichever earlier community it most overlaps with, so a label means the same group throughout.

You usually do not need this. When temporal_communities() runs with omega > 0, the interlayer coupling is the matching, performed inside the objective rather than as a post-hoc heuristic, and the labels are already consistent. Matching is for omega = 0, for per-bin detection, for comparing runs at different gamma, and for a partition computed elsewhere.

Usage

match_communities(
  x,
  method = c("hungarian", "greedy"),
  overlap = c("jaccard", "intersection"),
  threshold = 0.1
)

Arguments

Details

Overlaps are computed only over the vertices active in both bins, so a community whose members merely go quiet is not read as dissolving.

The event taxonomy is Greene, Doyle and Cunningham's (2010), with an optimal assignment step in place of their greedy one. A bin-$s$ community that overlaps two or more bin-$s{+}1$ communities above threshold has split: the assigned one inherits the label and the others are born, and every state involved is marked "split". The mirror case, two earlier communities feeding one later one, is a merge. When both descriptions fit, "split" is reported.

Labels are never recycled. A community that dissolves at bin 10 and an unrelated one born at bin 40 cannot share a label, so a long series does not silently reconnect two different groups.

Value

A dynet_communities frame with the same rows as x and three guarantees: community now carries the matched, time-consistent label; community_raw keeps the original per-bin label so the matching is auditable; and event records what happened to this state's community at this bin, one of "born", "persist", "split" or "merge". The community-level lifecycle table, which also carries "dissolve", is as.data.frame(x, what = "events").

References

Kuhn, H. W. (1955). The Hungarian method for the assignment problem. Naval Research Logistics Quarterly, 2(1-2), 83-97.

Jonker, R., & Volgenant, A. (1987). A shortest augmenting path algorithm for dense and sparse linear assignment problems. Computing, 38, 325-340.

Greene, D., Doyle, D., & Cunningham, P. (2010). Tracking the evolution of communities in dynamic social networks. ASONAM 2010, 176-183.

Palla, G., Barabasi, A.-L., & Vicsek, T. (2007). Quantifying social group evolution. Nature, 446, 664-667.

Cazabet, R., & Rossetti, G. (2019). Challenges in community discovery on temporal networks. In Temporal Network Theory, Springer, 181-197.

Examples

dn <- dynet(school_contacts)
loose <- temporal_communities(dn, omega = 0, step = 5, window = 5,
                              seeds = 1:3)
match_communities(loose)

Description

Graph properties measured on each time bin, returned as a time series. This is where a temporal network earns its keep: a single density for the whole course tells you nothing about a group that was dense in week two and silent in week five.

Usage

metrics(
  dn,
  measure = "density",
  sessions = c("bounded", "collapse", "separate"),
  sample = NULL,
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  basis = c("hops", "latency"),
  traversal_time = 0,
  plot = FALSE
)

Arguments

Details

"density" counts the any-time union of realised edges against eligible possible edges in each bin. The four temporal selectors instead integrate exact state over positive observed time inside every reporting window. "temporal_density" is binary occupied pair-time divided by all eligible nonloop ordered-pair time (directed) or dyad time (undirected). "observed_pair_density" uses the same numerator but restricts opportunity to pairs having endpoint-valid evidence anywhere in the complete stored history. That cohort is not reset by reporting windows or observation gaps. summary() reports the first quantity over the pooled full history.

If Y[r](t) is exact simultaneous endpoint eligibility, E[r](t) is binary edge presence, and H is the ever-observed pair set, the exposure ledgers are ⁠R = sum(r) integral(Y[r](t) dt)⁠, ⁠O = sum(r) integral(Y[r](t) E[r](t) dt)⁠, and ⁠R_H = sum(r in H) integral(Y[r](t) dt)⁠. The two occupancies are O/R and O/R_H and lie in ⁠[0, 1]⁠. Loops, weights, duplicates, and censor flags cannot multiply occupancy. Integration stops at the observation period, which defaults to the span of the data, so a last window reaching past the final spell is measured over its observed part only, and tiled windows pool to the whole-period value. tsna::tEdgeDensity() uses the same observation-period rule.

"onset_intensity" and "observed_pair_onset_intensity" divide the number of known raw spell starts by R and R_H. Each nonloop raw row, including a point contact, contributes once when its start is observed, not onset-censored, and has exactly eligible endpoints. Termini are not events; overlaps and duplicates remain distinct onsets. Intensities are nonnegative, unbounded, and measured in inverse network time. A zero denominator gives NA for every temporal selector, even when a point event exists. A positive denominator with a zero numerator gives zero. Therefore window = 0 makes all four temporal selectors undefined while snapshot measures retain their exact point-state meanings.

step and window are separate on purpose: step is how often you look, window is how much of the timeline each look takes in. A seven-day window stepped one day at a time smooths a noisy series without giving up daily resolution. They match time.interval and aggregate.dur in tsna::tSnaStats().

When vertex activity was declared in dynet(), every measure is computed on the endpoint-induced eligible vertex set for the window. Positive windows independently use the any-time vertex and edge unions before induction; window = 0 evaluates the exact state. Density and census opportunities, components, isolate counts, largest-component shares, and Freeman denominators therefore use eligible rather than fixed order.

"assortativity" is Newman's degree assortativity computed with the total degree (in plus out) at both ends of every arc, on directed and undirected snapshots alike. It is not the directed out-degree-to-in-degree variant igraph::assortativity_degree(directed = TRUE) reports, and the two disagree on directed data.

"centralization_closeness" is a Freeman centralisation of this package's own closeness (reachable vertices divided by reachable distance, so it is defined on a disconnected snapshot), with the theoretical maximum of that score: n - 1 for a directed snapshot (a single arc from the centre) and n - 2 for an undirected one (one isolated dyad). It matches sna::centralization(closeness) on connected snapshots and not on disconnected ones, where sna's closeness is zero everywhere.

Krackhardt's four indices – "connectedness", "efficiency", "hierarchy" and "lubness" – describe how far a directed network departs from a pure out-tree. "hierarchy" and "lubness" are undefined on some graphs (no connected pair, no component of three) and report NaN rather than a number that would mislead.

Triad census cost grows with the cube of the vertex count. On a network of a few hundred vertices it is the slowest measure here by a wide margin.

The lightweight structural selectors use the binary, loop-free induced snapshot. Directed total degree is in-degree plus out-degree; "degree_variance" is the sample variance across eligible vertices. "mean_degree" is the mean out-degree for a directed graph (identically, the mean in-degree) and the ordinary mean degree for an undirected graph; this matches ERGM's meandeg statistic. "indegree_1_5" and "outdegree_1_5" sum the corresponding vertex degrees raised to 1.5. Directed "triangles" is the sum of cyclic and transitive triples, while an undirected triangle is counted once. A concurrent vertex has relations to at least two distinct neighbours active at the same instant, so a reciprocal dyad still supplies only one neighbour. Unlike the other structural selectors, concurrency is not read from the window's union snapshot: with a positive window, two ties that fall in the same window without overlapping in time do not make their shared vertex concurrent. A vertex counts in a window when it is concurrent at any instant inside it; "concurrent_nodes" is the number of such vertices and "concurrent_share" divides it by the window's eligible vertices. With window = 0 the snapshot is itself an instant, so both readings coincide. Half-open spells that only meet at a boundary do not overlap, and a point contact is concurrent with every relation active at its timestamp. mixing() answers a different question – which groups are connected somewhere in the window – and requires no simultaneity. "in_2stars" and "out_2stars" sum choose(degree, 2) over directed in- and out-degrees. Directed "two_paths" counts ordered i -> j -> k paths with i != k; undirected two-paths count each unordered wedge once. Empty eligible snapshots return zero for all selectors.

Value

A dynet_metric at graph level: one row per time point and measure, with columns session (only under sessions = "separate", the one mode that keeps session labels apart), time, measure and value. "triads" contributes sixteen rows per time point, whose measure entries are triad_003, triad_012, ..., triad_300. Print it, summary() it, plot() it, or take the plain frame with as.data.frame().

Conditions

Errors: dynet_unknown_measure (a name outside the forty above), dynet_needs_directed (one of the eight direction-reading selectors on an undirected network), dynet_no_sessions (sessions = "separate" without a session column), dynet_outside_observation (the requested range misses observed support; it also carries dynet_bad_input), and dynet_bad_input for every other broken contract – dn not a dynet, a non-character measure, an empty measure, an out-of-range start, end, step or window, end before start, and step combined with window = "all".

Warning: dynet_deprecated for the retired sample argument.

References

Freeman, L. C. (1979). Centrality in social networks: conceptual clarification. Social Networks, 1, 215-239. doi:10.1016/0378-8733(78)90021-7

Butts, C. T., Leslie-Cook, A., Krivitsky, P. N., & Bender-deMoll, S. (2024). networkDynamic: Dynamic Extensions for Network Objects, version 0.11.5. doi:10.32614/CRAN.package.networkDynamic

Holme, P., & Saramaki, J. (2012). Temporal networks. Physics Reports, 519(3), 97-125. doi:10.1016/j.physrep.2012.03.001

Latapy, M., Viard, T., & Magnien, C. (2018). Stream graphs and link streams for the modeling of interactions over time. Social Network Analysis and Mining, 8, 61. doi:10.1007/s13278-018-0537-7

Andersen, P. K., & Gill, R. D. (1982). Cox's regression model for counting processes: a large sample study. Annals of Statistics, 10, 1100-1120. doi:10.1214/aos/1176345976

Krackhardt, D. (1994). Graph theoretical dimensions of informal organizations. In Computational Organization Theory (pp. 89-111). Lawrence Erlbaum.

Newman, M. E. J. (2002). Assortative mixing in networks. Physical Review Letters, 89, 208701. doi:10.1103/PhysRevLett.89.208701

Morris, M., & Kretzschmar, M. (1997). Concurrent partnerships and the spread of HIV. AIDS, 11(5), 641-648. doi:10.1097/00002030-199705000-00012

Holland, P. W., & Leinhardt, S. (1976). Local structure in social networks. Sociological Methodology, 7, 1-45. doi:10.2307/270703

Wasserman, S., & Faust, K. (1994). Social Network Analysis: Methods and Applications. Cambridge University Press.

Examples

dn <- dynet(school_contacts)
metrics(dn, measure = "density")
metrics(dn, measure = c("density", "reciprocity", "transitivity"))
metrics(dn, measure = "density", step = 1, window = 3)
dyads <- metrics(dn, measure = c("mutual", "asymmetric"))
plot(dyads)

Description

How much each kind of vertex interacted with each other kind, in every time bin. This is the question a temporal network answers that a static one cannot: not whether high and low achievers mixed, but when they did, and whether the pattern held or decayed.

The grouping variable comes from the vertex attributes supplied to dynet() through its nodes argument.

Usage

mixing(
  dn,
  attribute,
  sessions = c("bounded", "collapse", "separate"),
  sample = NULL,
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  plot = FALSE
)

Arguments

Details

Each cell is a raw count of distinct active binary vertex dyads. Repeated, overlapping, or split spells and edge weights do not multiply a dyad. Retained self-loops count once. For directed networks, every ordered group pair is reported and

$M_{ab}=\sum_{u:g(u)=a}\sum_{v:g(v)=b}Y_{uv}.$

The row and column margins are grouped outdegree and indegree, and the table sum is the active directed edge count including retained loops.

Undirected networks report one lexicographically canonical cell for each unordered group pair, with display labels such as "A -- B". A within-group edge or loop contributes once to its diagonal cell. The group stub margin is

$d_a=2M_{aa}+\sum_{b\ne a}M_{\min(a,b),\max(a,b)},$

so the margins sum to twice the table total. These are unnormalised counts, not Newman's mixing proportions.

Missing attribute values are retained as a collision-safe explicit group ordered after observed labels. Bounded and collapsed modes both use the binary calendar union: a dyad active in two sessions at the same time counts once. Separate mode returns session-local tables over the fixed group universe. Every supported cell is emitted, including zeros. Declared vertex activity first induces the endpoint-valid snapshot. The complete group-cell universe remains fixed, but inactive vertices and eligible isolates contribute no dyad.

Value

A dynet_metric at graph level with one row per time point and group pair. The columns are session (only under sessions = "separate", the one mode that keeps session labels apart), time, measure, value, from_group and to_group. Directed measure labels use "A -> B"; undirected labels use "A -- B". value is the active binary-dyad count, and the authoritative from_group and to_group columns identify the cell. Attributes record unit, pair-domain, normalisation, weight, loop, missing-group, and session-aggregation conventions.

Conditions

Errors: dynet_unknown_attribute (no such vertex attribute), dynet_no_sessions (sessions = "separate" without a session column), dynet_outside_observation (the requested range misses observed support; it also carries dynet_bad_input), and dynet_bad_input for every other broken contract – dn not a dynet, an attribute that is not a single column name, and an out-of-range start, end, step or window.

Warning: dynet_deprecated for the retired sample argument.

References

Newman, M. E. J. (2003). Mixing patterns in networks. Physical Review E, 67, 026126. doi:10.1103/PhysRevE.67.026126

Morris, M., Handcock, M. S., & Hunter, D. R. (2008). Specification of exponential-family random graph models: terms and computational aspects. Journal of Statistical Software, 24(4). doi:10.18637/jss.v024.i04

Examples

dn <- dynet(forum_posts, thread = "thread", nodes = forum_people)
role_mixing <- mixing(dn, attribute = "role")
role_mixing
plot(role_mixing)

Description

The participant table accompanying mooc_posts: every person who appears as a sender or a receiver there, with the self-reported experience level as the chapter's integer code and as the label it recodes the code into and uses as the mixing attribute.

Usage

mooc_people

Format

A data frame with 445 rows and 3 columns:

name

Character. Participant identifier, matching the sender and receiver columns of mooc_posts.

experience

Integer. Self-reported experience level: 1 expert, 2 student, 3 teacher.

expert_level

Character. The same level as Expert, Student or Teacher.

Source

As mooc_posts: Saqr (2024), doi:10.1007/978-3-031-54464-4_17.

See Also

mooc_posts; vignette("ch17-temporal-networks").

Examples

participants <- dynet(mooc_posts, from = "sender", to = "receiver",
                      time = "timestamp", thread = "discussion",
                      nodes = mooc_people)
as.data.frame(participants, what = "nodes")

Description

The discussion log of chapter 17 of Learning Analytics Methods and Tutorials (Saqr, 2024), one row per post in the Digital Learning Transition MOOC, April to June 2013. A post names the participant who wrote it and the participant it answers, so a tie runs from sender to receiver; discussion is the thread the post belongs to, which is what makes the log threaded in the sense dynet() means by ⁠thread =⁠.

Usage

mooc_posts

Format

A data frame with 2529 rows and 4 columns:

sender

Character. The participant who wrote the post.

receiver

Character. The participant the post answers.

timestamp

POSIXct (UTC). When the post was made, from 2013-04-04 16:32 to 2013-06-16 17:12.

discussion

Character. Thread title; 338 distinct threads.

Details

Only the four columns the chapter's analysis reads are kept; the category hierarchy and comment identifiers of the published file are dropped.

Source

Saqr, M. (2024). Temporal network analysis: Introduction, methods and analysis with R. In M. Saqr & S. López-Pernas (Eds.), Learning Analytics Methods and Tutorials. Springer. doi:10.1007/978-3-031-54464-4_17. Data from https://github.com/lamethods/data, directory ⁠6_snaMOOC⁠, prepared by data-raw/mooc_forum.R.

See Also

mooc_people for the participants, and vignette("ch17-temporal-networks") for the chapter's analysis.

Examples

dn <- dynet(mooc_posts, from = "sender", to = "receiver",
            time = "timestamp", thread = "discussion")
dn

Description

Counts the 40 Paranjape three-edge, three-node temporal motif classes, in the class ordering of raphtory 0.17.0 so a census can be checked against an independent implementation index by index.

Usage

motifs(
  dn,
  delta,
  output = c("global", "local"),
  sessions = c("bounded", "collapse", "separate"),
  start = NULL,
  end = NULL
)

Arguments

Details

The definition. Three incompatible motif families exist in the literature. This adopts Paranjape, Benson & Leskovec (2017): exactly three edge events on at most three distinct vertices, with t_last - t_first <= delta over the three times in sorted order. Kovanen et al. (2011) instead allow arbitrary size and bound consecutive gaps, which is a strictly weaker condition and agrees only for two-edge patterns; that family's instance count is unbounded and does not reduce to a fixed census.

The three edges are three distinct events; the same pair may repeat, which is exactly what the two-node classes are. Loops are excluded, and instances may share edges – every qualifying triple is counted, as in the reference implementations. Edge-disjoint counting is a different and much harder problem, and is not what any reference computes.

Local counting is not uniform across families, and this is raphtory's rule, adopted verbatim. For a star only the centre counts the instance; for a triangle all three vertices do; for a two-node motif the global census itself already records one count at each endpoint's class. So the local counts sum to the global counts for stars and two-node motifs, and to three times the global counts for triangles.

Simultaneous events are ordered by the deterministic key ⁠(time, from, to, spell)⁠. Paranjape assumes distinct timestamps; this is Dynet's choice, so that a census never depends on input row order.

The enumeration is the direct one, quadratic in the number of events sharing a window. Paranjape's incremental algorithm is linear; this is not it, and a very large delta on a bursty network will be slow.

Value

A dynet_motifs data frame. Under output = "global" the columns are motif (the 1-based raphtory index), family, pattern and count; under "local" a node column precedes them. A leading session column is present under sessions = "separate". All 40 classes are always present, zeros included – a census with rows silently missing is not a census. Print it, summary() it, plot() it, or take the plain frame with as.data.frame().

Conditions

Errors: dynet_needs_directed on an undirected network, since the 40-class taxonomy is defined by edge directions and has no honest undirected reading; dynet_bad_input when delta is missing, not a single finite non-negative number, or when dn is not a dynet; dynet_no_sessions under sessions = "separate" without a session column; dynet_count_overflow when a class exceeds 2^53.

References

Paranjape, A., Benson, A. R., & Leskovec, J. (2017). Motifs in temporal networks. WSDM '17, 601-610. doi:10.1145/3018661.3018731

Kovanen, L., Karsai, M., Kaski, K., Kertesz, J., & Saramaki, J. (2011). Temporal motifs in time-dependent networks. Journal of Statistical Mechanics, P11005. doi:10.1088/1742-5468/2011/11/P11005

See Also

gaps() for choosing delta, and pshifts() for the dyadic turn-taking census, which counts the same events with a different arity.

Examples

dn <- dynet(school_contacts)
census <- motifs(dn, delta = 2)
census

Description

The Mucha et al. (2010) quality function: how much better a partition explains the network than a degree-preserving null does, computed slice by slice with the slices tied together by the interlayer coupling omega.

Score a partition you already have – a class roster, a set of research groups, an externally computed clustering – or score the one temporal_communities() found. It is the objective that verb maximises, so the two round-trip with no reshaping by the caller.

Usage

multislice_modularity(
  dn,
  membership = NULL,
  gamma = 1,
  omega = 1,
  coupling = c("ordinal", "categorical"),
  sessions = c("bounded", "collapse", "separate"),
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL
)

Arguments

Details

With $A_{ijs}$ the weight of edge $i$–$j$ in slice $s$, $k_{is}$ its slice-local strength, $2m_s$ the slice total, $\omega_{jsr}$ the coupling of vertex $j$ between slices $s$ and $r$, and $2\mu = \sum_{js}(k_{js} + \sum_r \omega_{jsr})$,