path.visibility {streamDAG}

Path Visibilities

Description

Functions detect and summarize visibilities of path nodes from one or several source nodes to an sink. Specifically, the function The function path.visibility determines path visibilities from single source node to a single sink. multi.path.visibility Generates tables of path visibilities and visibility summaries for multiple source nodes to a single sink.

Ordering of nodes, vitally important to the calculation of visibility is currently obtained by identifying paths from each source node to the sink. The sum of node distances in each path are then sorted decreasingly to define an initial order for calculating visibilities. It is currently assumed that the user will manually handle disconnected paths via the source argument of visibility functions. Use of source nodes disconnected to the sink will result in the message: "only use source nodes connected to sink". Because of this situation disconnected graphs will be handled by a function in development single.node.visibility.

Usage

path.visibility(G, degree = "in", source = NULL, sink = NULL, weights = NULL)

multi.path.visibility(G, degree = "in", source = NULL, sink = NULL, 
weights = NULL, autoprint = TRUE)

Arguments

G

Graph of class "igraph". See graph_from_literal

degree

One of "out" for outdegree, "in" for indegree or "all" for the sum of the two.

source

A starting node for a path. The function multi.path.visibility allows multiple starting nodes.

sink

An ending node for a path.

weights

If !null, refers to a 1 \times n data.frame of weights, with the data.frame name attribute in weights corresponding to node names in G.

autoprint

Logical. Should table summary of nodal visibilities be automatically printed or made ?

Details

Following Lacasa et al. (2008), let t_a represent the occurrance number of the ath node in a time series or stream path, and let y_a represent a data outcome from the ath node. Nodes a and b will have visibility if all other data, y_c, between a and b fufill:

y_c < y_b + (y_a - y_b)\frac{t_b - t_c}{t_b - t_a}.

Value

The function path.visibility returns a symmetric matrix whose upper triangle denotes nodal co-visibilities. The lower triangle is left empty for efficiency. Reading down a column in the upper triangle shows upstream visibilites to and from a node, while reading across rows shows downstream visibilities.

The function multi.path.visibility returns a list containing the three objects. The first is printed and the latter two are invisible by default.

visibility.summary

The printed result is a matrix of path visibity counts for a node, with respect to upstream (to), downstream (from), and combined directions (both).

complete.matrix

Analogous, to path.visibility, this result attempts to synthesize visibilities within source-to-sink paths for all requested sources into a single matrix.

all.matrices

A list containing path.visibility summary matrices for each source-to-sink path.

Output is summarized based on a deduced ordering of nodes from sources to sin. The ordering is based on nodal path lengths.

Author(s)

Ken Aho, Gabor Csardi wrote degree and shortest_paths.

References

Lacasa, L., Luque, B., Ballesteros, F., Luque, J., & Nuno, J. C. (2008). From time series to complex networks: The visibility graph. Proceedings of the National Academy of Sciences, 105(13), 4972-4975.

See Also

degree, shortest_paths

Examples

A <- graph_from_literal(a --+ b, c --+ d, d --+ e, b --+ e, 
e --+ j, j --+ m, f --+ g, g --+ i, h --+ i, i --+ k, k --+ l, 
l --+ m, m --+ n,  n --+ o)

path.visibility(A, source = "a", sink = "o")
  
multi.path.visibility(A, source = c("a","c","f","h"), 
sink = "o")

# From Lacasa et al. (2008)

B <- graph_from_literal(a --+ b --+ c --+ d --+ e --+ f --+ g)
weights <- data.frame(matrix(nrow = 1, data = c(0.87, 0.49, 0.36, 0.83, 0.87, 0.49, 0.36))) 
names(weights) = letters[1:7]
path.visibility(B, source = "a", sink = "g", weights = weights)