durations: How long each relationship lasted

In Dynet: Tidy Temporal Network Analysis

How long each relationship lasted

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

dn	A temporal network from dynet().
measure	For pair unit, one or more of "events" (number of spells), "total" (summed duration), "union" (binary pair occupancy), "mean", "median", "first", and "last"; its default is c("events", "total", "mean"). For spell unit, one or more of "duration", "first", and "last"; its default is "duration". Vertex-activity unit allows the pair-like measures and defaults to "events", "total", and "union"; vertex-spell unit allows the same measures as edge spell and defaults to "duration". Node-ties unit allows "events" (incident raw-spell endpoint stubs), "total" (their summed endpoint-valid duration), and "union" (binary incident calendar exposure), defaulting to events and total. A measure the chosen unit does not offer raises a dynet_unknown_measure error.
sessions	How to treat sessions: "bounded" (the default), "collapse" or "separate", as in centrality_series().
censored	Whether to "include" known follow-up, the default, or "exclude" an entire edge raw spell or canonical vertex component with either explicit outer censor flag. Administrative observation cuts never cause exclusion.
unit	"pair", the default, retains the existing pair summary and adds union duration; "spell" returns one row per retained raw edge-spell identity; "vertex_activity" returns fixed-node aggregates; "vertex_spell" returns retained canonical vertex-activity identities; "node_ties" returns fixed-node incident-tie quantities.
mode	For unit = "node_ties", "out" (the default), "in", or "all" endpoint incidence. Undirected networks normalise every request to "all". Supplying mode explicitly for any other duration unit raises a dynet_incompatible_duration_mode error; leaving it at its default is what makes the other units legal.
plot	Whether to draw the result as well as return it. Drawing is a side effect in the manner of graphics::hist(): the verb still returns its tidy table, invisibly when it has drawn, so plot = TRUE saves the wrapping plot() call without changing what comes back. Use plot() on the result when the figure needs arguments of its own.

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")

Dynet documentation built on Oct. 7, 2026, 5:08 p.m.