pathways() reports whole journeys rather than per-vertex summaries: one
row per distinct route, ranked by how many optimal routes follow it. It
answers "which pathways does this network actually use", where
path_trajectories() answers "where do the routes diverge" and paths()
answers "who is reachable".
Arguments
- dn
A temporal network from
dynet().- from
Optional source vertex. A name gives the routes leaving that vertex, and several names give the routes leaving each of them. The default,
NULL, pools every vertex, which is the network-wide question, and is the only case that adds afromcolumn naming each route's source; a named source is already the first step of everyroutestring.- top
Optional number of routes to keep, most frequent first. The default keeps all of them.
- min_hops
Shortest route to report. Defaults to one, which drops the zero-hop route from a vertex to itself.
- ...
Passed to
paths(), sostart,end,at,direction,sessionsandtraversal_timeall apply.- 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, soplot = TRUEsaves the wrappingplot()call without changing what comes back. Useplot()on the result when the figure needs arguments of its own.
Value
An object of class dynet_pathways, a data frame with one row per
distinct route, most frequent first: route, the vertex sequence joined
by arrows; endpoint, where it lands; count, how many optimal routes
follow it; share, its fraction of every counted route, so the shares of
a result limited by top do not sum to one; n_hops; and
arrival_time, the earliest time the route lands. Pooling over every
source adds from as the first column. Use as.data.frame() for a plain
frame and as.data.frame(x, what = "steps") for the per-hop timing of
the routes that were kept.
An unknown from raises dynet_unknown_node; a top or min_hops that
is not one finite number in range raises dynet_bad_input; and a query
that leaves no route of at least min_hops hops raises
dynet_empty_result. Conditions raised by paths() on the arguments
passed through ... reach the caller unchanged.
Details
The result is already ordered and already carries the share of the total,
so a caller never sorts or subsets it; top limits it in the call.
Every optimal route that paths() counts is one route here, the route to
a vertex that lies on the way to another included, so for one source
sum(count) equals the summed n_paths of the vertices reached in at
least min_hops hops.
Routes are keyed on their vertex sequence. The trajectory tree keys a node on vertex and time, so one sequence realised through different contacts appears there as several branches; those are one pathway here and their counts are added. The arrival time loses nothing in that merge: a vertex sequence ends at one endpoint, and every counted route to it attains the same optimum, which a test asserts. Intermediate hop times can differ between the merged realisations; the steps table keeps the first in the order of the path result.
See also
paths() for reachability, path_trajectories() for the prefix
tree those routes share.
Examples
dn <- dynet(school_contacts)
pathways(dn, from = "Ana")
#> # Time-respecting pathways (13 distinct routes)
#> # 18 optimal routes counted
#> route endpoint count share n_hops
#> Ana -> Jonas -> Kira -> Ben Ben 3 0.16666667 3
#> Ana -> Jonas -> Kira -> Ben -> Eve Eve 3 0.16666667 4
#> Ana -> Jonas -> Kira Kira 2 0.11111111 2
#> Ana -> Cara Cara 1 0.05555556 1
#> Ana -> Jonas Jonas 1 0.05555556 1
#> Ana -> Mira Mira 1 0.05555556 1
#> Ana -> Cara -> Finn Finn 1 0.05555556 2
#> Ana -> Cara -> Nils Nils 1 0.05555556 2
#> Ana -> Mira -> Gita Gita 1 0.05555556 2
#> Ana -> Cara -> Finn -> Iris Iris 1 0.05555556 3
#> Ana -> Cara -> Finn -> Leo Leo 1 0.05555556 3
#> Ana -> Cara -> Nils -> Hugo Hugo 1 0.05555556 3
#> arrival_time
#> 9.59
#> 11.66
#> 6.12
#> 6.67
#> 2.12
#> 6.36
#> 6.96
#> 7.51
#> 6.36
#> 10.00
#> 9.65
#> 7.98
#> # 1 more of the 13 kept. Use top = to keep a different number.
pathways(dn, from = c("Ana", "Ben", "Kira"), top = 5)
#> # Time-respecting pathways (41 distinct routes, showing 5)
#> # 53 optimal routes counted
#> route endpoint count share n_hops
#> Ana -> Jonas -> Kira -> Ben Ben 3 0.05660377 3
#> Kira -> Leo -> Finn -> Nils Nils 3 0.05660377 3
#> Ana -> Jonas -> Kira -> Ben -> Eve Eve 3 0.05660377 4
#> Ana -> Jonas -> Kira Kira 2 0.03773585 2
#> Kira -> Leo -> Hugo Hugo 2 0.03773585 2
#> arrival_time
#> 9.59
#> 6.31
#> 11.66
#> 6.12
#> 6.76