zenplots (version 0.0-4)

zenpath: Constructing Zenpaths and Related Tools

Description

Constructing zenpaths and tools for extracting, connecting and displaying pairs, as well as, grouping and indexing data structures.

Usage

zenpath(x, pairs = NULL,
        method = c("front.loaded", "back.loaded", "balanced",
                   "eulerian.cross", "greedy.weighted", "strictly.weighted"),
        decreasing = TRUE)
extract_pairs(x, n)
connect_pairs(x, duplicate.rm = FALSE)
graph_pairs(x, var.names = NULL)
groupData(x, indices, byrow = FALSE)
indexData(x, indices)

Arguments

x

for

zenpath():

for method

"front.loaded":

single integer.

"back.loaded":

as for method = "front.loaded".

"balanced":

as for method = "front.loaded".

"eulerian.cross":

two integers representing the group sizes.

"greedy.weighted":

numeric weight vector (or matrix or distance matrix).

"strictly.weighted":

as for method = "greedy.weighted".

extract_pairs():

the path, a vector or list of indices of the variables to be plotted.

connect_pairs():

two-column matrix or a list containing vectors of length two representing the pairs to be connected.

graph_pairs():

matrix or list of pairs along a zenpath. Can also be a list containing vectors of length larger than two (then being interpreted as connected pairs).

groupData():

matrix (or an object convertible to such via as.matrix()).

indexData():

matrix or data.frame (most useful for the latter).

pairs

two-column matrix containing (row-wise) the pairs of connected variables to be sorted according to the weights. pairs is only used for methods greedy.weighted, strictly.weighted and can be NULL in which case a default is constructed in lexicographical order.

method

character string indicating the sorting method to be used. Available are:

"front.loaded":

sort all pairs such that the first variables appear the most frequently early in the sequence.

"back.loaded":

sort all pairs such that the later variables appear the most frequently later in the sequence.

"balanced":

sort all pairs such that all variables appear in balanced blocks throughout the sequence (a Hamiltonian Decomposition).

"eulerian.cross":

generate a sequence of pairs such that each is formed with one variable from each group.

"greedy.weighted":

sort all pairs according to a greedy (heuristic) Euler path visiting each edge precisely once.

"strictly.weighted":

this method strictly respects the order given by the weights, so the first, second, third, etc. adjacent pair of numbers of the output of zenpath() corresponds to the pair with largest, second-largest, third-largest, etc. weight.

decreasing

logical indicating whether the sorting is done according to increasing or decreasing weights.

n

vector of length two giving the number of pairs to extract from the path x (if NULL, all pairs are returned (nothing extracted); if of length one, it is replicated). The first number corresponds to the beginning of the path, the second to the end; at least one of the two numbers should be >= 1.

duplicate.rm

logical indicating whether equal pairs (up to permutation) are omitted.

var.names

names of the variables appearing in x.

indices

groupData():

list of vectors of indices according to which x is grouped.

indexData():

vector of column indices of x (typically obtained from zenpath()).

byrow

logical indicating whether the grouping is done by row (byrow = TRUE) or by column (byrow = FALSE).

Value

zenpath() returns a sequence of variables (indices or names, possibly a list of such), which can then be used to index the data (via groupData()) for plotting via zenplot().

extract_pairs() returns an object of the same type as the input x but (possibly) shortened. It extracts the first/last so-many pairs of x.

connect_pairs() returns a list of (possibly connected) pairs, so a list of vectors of length at least 2.

groupData() returns a list of (grouped) matrices. This is then typically passed on to zenplot().

indexData() returns an object as x (typically a data.frame or matrix) containing x indexed by indices.

See Also

zenplot() which provides the zenplot.

Examples

# NOT RUN {
## A baby example to see how groupData() works
A <- matrix(1:12, ncol = 3)
lst <- list(1, list(2:3))
groupData(A, indices = lst) # split the matrix according to the grouping given by lst

## Some calls of zenpath()
zenpath(10) # integer argument
## Note that the result is of length 50 > 10 choose 2 as the underlying graph has to
## be even (and thus edges are added here)
(zp <- zenpath(c(3, 5), method = "eulerian.cross")) # integer(2) argument

## Extract the first and last three pairs of indices
extract_pairs(zp, n = 3)

## A more sophisticated example
nVars <- 5 # number of variables
set.seed(271)
x <- runif(nVars*(nVars-1)/2) # weights
## Construct the pairs
pairs <- expand.grid(1:nVars, 1:nVars)[,2:1]
pairs <- pairs[pairs[,1] < pairs[,2],]
pairs <- matrix(unlist(pairs), ncol = ncol(pairs))
stopifnot(length(x) == nrow(pairs)) # sanity check
## Manually compute the result of method = "strictly.weighted" and group the pairs
## 1) Sort pairs according to the weights x and plot the variables
w <- order(x, decreasing = TRUE)
(pairs. <- pairs[w,])
library(graph)
plot(graph_pairs(pairs.)) # depict all pairs (edge = pair)
## 2) Now go through the rows and determine the sequence of adjacent pairs
##    which can be plotted with a zenplot
res <- list(c(5,3,1),
            c(3,2,5),
            c(4,1,5),
	    c(1,2),
	    c(5,4,3),
	    c(2,4))
## Call zenpath() and check whether we get the same
(zp  <- connect_pairs(zenpath(x, pairs = pairs, method = "strictly.weighted")))
stopifnot(identical(zp, lapply(res, as.integer)))

## Extract the first and last three pairs of indices
(ezp <- extract_pairs(zp, n = 3))

## Another example based on a matrix of (trivial) weights
## This also shows that an input matrix 'x' does not have to
## be symmetric. In that case, the lower triangular matrix is used.
d <- 10
x <- matrix(1, nrow = d, ncol = d)
k <- 1
for(j in 1:(d-1)) {
    for(i in (j+1):d) {
        x[i,j] <- k
        k <- k+1
    }
}
x

## Compute the 'strictly.weighted' zenpath (all pairs sorted in decreasing order)
k <- 10 # bottom and top number of pairs (k most extreme pairs)
zpath <- zenpath(x, method = "strictly.weighted") # compute path over all pairs (decreasing weights)
stopifnot(sapply(1:length(zpath), function(i) x[zpath[[i]][1], zpath[[i]][2]]) ==
          45:1) # check
zpath <- connect_pairs(zpath) # connect the pairs
zp <- extract_pairs(zpath, n = c(3, 0)) # grab out the top three pairs
# }