sumHPD: Summarize a Hive Plot Data Object and Optionally Run Some...

In HiveR: 2D and 3D Hive Plots for R

Summarize a Hive Plot Data Object and Optionally Run Some Checks

Description

This function summarizes a HivePlotData object in a convenient form. Optionally, it can run some checks for certain conditions that may be of interest. It can also output a summary of edges to be drawn, either as a data frame or in a LaTeX ready form, or a data frame of orphaned nodes.

Usage

sumHPD(
  HPD,
  chk.all = FALSE,
  chk.sm.pt = FALSE,
  chk.ax.jump = FALSE,
  chk.sm.ax = FALSE,
  chk.orphan.node = FALSE,
  chk.virtual.edge = FALSE,
  plot.list = FALSE,
  tex = FALSE,
  orphan.list = FALSE
)

Arguments

HPD	An object of S3 class HivePlotData.
chk.all	Logical; should all the checks below be run? See Details.
chk.sm.pt	Logical; should the edges be checked to see if any of them start and end on the same axis with the same radius? See Details.
chk.ax.jump	Logical; should the edges be checked to see if any of them start and end on non-adjacent axes, e.g. axis 1 –> axis 3? See Details.
chk.sm.ax	Logical; should the edges be checked to see if any of them start and end on the same axis?
chk.orphan.node	Logical; should orphan nodes be identifed? Orphan nodes have degree 0 (no incoming or outgoing edges).
chk.virtual.edge	Logical; should the edges be checked to see if any of them start and end on different nodes which happen to be at the same radius on the same axis? See Details.
plot.list	Logical; should a data frame of edges to be drawn be returned?
tex	Logical; should the plot.list be formatted for LaTeX?
orphan.list	Logical; should a data frame of orphaned nodes be returned?

Details

Argument chk.sm.pt applies only to hive plots of type = 2D. It checks to see if any of the edges start and end at the same node id. These by definition exist at the same radius on the same axis, which causes an error in plotHive since you are trying to draw an edge of length zero (the actual error message is Error in calcCurveGrob(x, x$debug) : End points must not be identical. Some data sets may have such cases intrinsically or due to data entry error, or the condition may arise during processing. Either way, one needs to be able to detect such cases for removal or modification. This argument will tell you which nodes cause the problem.

Argument chk.virtual.edge applies only to hive plots of type = 2D and is similiar to chk.sm.pt above except that it checks for virtual edges. These are edges start and end on the same axis at the same radius but at different node id's (in other words, two nodes have the same radius on the same axis). This condition gives the same error as above. It is checked for separately as it arises via a different problem in the construction of the data.

Argument chk.ax.jump applies only to hive plots of type = 2D. It checks to see if any of the edges jump an axis, e.g. axis 1 –> axis 3. This argument will tell you which nodes are at either end of the jumping edge. Jumping should should be avoided in hive plots as it makes the plot aesthetically unpleasing. However, depending upon how you process the data, this condition may arise and hence it is useful to be able to locate jumps.

Value

A summary of the HivePlotData object's key characteristics is printed at the console, followed by the results of any checks set to TRUE. The format of these results is identical to that of plot.list described just below, except for the orphan node check. This is formatted the same as HPD$nodes; see ?HPD for details.

If plot.list = TRUE, a data frame containing a list of the edges to be drawn in a format suitable for troubleshooting a plot. If tex = TRUE as well, the data frame will be in a format suitable for pasting into a LaTeX document. The data frame will contain rows describing each edge to be drawn with the following columns: node 1 id, node 1 axis, node 1 label, node 1 radius, then the same info for node 2, then the edge weight and the edge color.

If orphan.list = TRUE a data frame giving the orphan nodes is returned. If you want both plot.list and orphan.list you have to call this function twice.

Author(s)

Bryan A. Hanson, DePauw University. [e-mail]

Examples

set.seed(55)
test <- ranHiveData(nx = 4, ne = 5, desc = "Tiny 4D data set")
out <- sumHPD(test, chk.all = TRUE, plot.list = TRUE)
print(out)

HiveR documentation built on Sept. 12, 2024, 7:25 a.m.