plotSequence {BoolNet}

Plot a sequence of states

Description

Visualizes sequences of states in synchronous Boolean networks, either by drawing a table of the involved states in two colors, or by drawing a graph of transitions between the successive states.

Usage

plotSequence(network, 
             startState, 
             includeAttractorStates = c("all","first","none"), 
             sequence,
             title = "", 
             mode=c("table","graph"),
             plotFixed = TRUE, grouping = list(),
             onColor="#4daf4a", 
             offColor = "#e41a1c",
             layout, 
             drawLabels=TRUE, 
             drawLegend=TRUE, 
             highlightAttractor=TRUE,
             reverse = FALSE,
             borderColor = "black", 
             eps=0.1,
             attractor.sep.lwd = 2, 
             attractor.sep.col = "blue",
             ...)

Arguments

network

An object of class BooleanNetwork or SymbolicBooleanNetwork for which a sequence of state transitions is calculated

startState

The start state of the sequence

includeAttractorStates

Specifies whether the actual attractor states are included in the plot or not (see also getPathToAttractor). If includeAttractorStates = "all" (which is the default behaviour), the sequence ends when the attractor was traversed once. If includeAttractorStates = "first", only the first state of attractor is added to the sequence. If includeAttractorStates = "none", the sequence ends with the last non-attractor state.

sequence

The alternative call to plotSequence requires the specification of the sequence itself instead of the network and the start state. The sequence must be provided as a data frame with the genes in the columns and the successive states in the rows. For example, sequences can be obtained using getPathToAttractor or getAttractorSequence (however, the specialized plot plotAttractors exists for attractors).

title

An optional title for the plot

mode

Switches between two kinds of attractor plots. See Details for more information. Default is "table".

plotFixed

This optional parameter is only used if mode="table". If this is true, genes with fixed values are included in the plot. Otherwise, these genes are not drawn.

grouping

This optional parameter is only used if mode="table" and specifies a structure to form groups of genes in the plot. This is a list with the following elements:

class

A vector of names for the groups. These names will be printed in the region belonging to the group in the plot.

index

A list with the same length as class. Each element is a vector of gene names or gene indices belonging to the group.

onColor

This optional parameter is only used if mode="table" and specifies the color value for the 1/ON values in the table. Defaults to green.

offColor

This optional parameter is only used if mode="table" and specifies the color value for the 0/OFF values in the table. Defaults to red.

layout

If mode="graph", this parameter specifies a layouting function that determines the placement of the nodes in the graph. Please refer to the layout manual entry in the igraph package for further details. By default, the nodes are placed in a horizontal line.

drawLabels

This parameter is only relevant if mode="graph". It determines whether the nodes of the graph are annotated with the corresponding values of the genes in the attractor states.

drawLegend

Specifies whether a color key for the ON/OFF states is drawn if mode="table". Defaults to TRUE.

highlightAttractor

If set to true, the attractor states are highlighted in the plot. If mode="table", a line is drawn at the begin of the attractor, and the states are labeled correspondingly. If mode="graph", the attractor transitions are drawn as bold lines. Information on the attractor must be supplied in the attribute attractor of the sequence, which is a vector of indices of the states that belong to the attractor. This attribute is usually present if the sequence was obtained using getPathToAttractor.

reverse

Specifies the order of the genes in the plot. By default, the first gene is placed in the first row of the plot. If reverse=TRUE (which was the default until BoolNet version 2.0.2), the first gene in the network is placed in the bottom row of the plot.

borderColor

Specifies the border or seprating color of states in an attractor. Defaults to "black".

eps

Specifies plotting margin for the sequence of states. Defaults to 0.1.

attractor.sep.lwd

Specifies the line width of the attractor separator. Defaults to 2.

attractor.sep.col

Specifies the line color of the attractor separator. Defaults to "blue".

...

Further graphical parameters to be passed to plot.igraph if mode="graph".

Details

This function comprises two different types of plots:

The "table" mode visualizes the gene values of the states in the sequence. The figure is a table with the genes in the rows and the successive states of the sequence in the columns. Cells of the table are (by default) red for 0/OFF values and green for 1/ON values. If grouping is set, the genes are rearranged according to the indices in the group, horizontal separation lines are plotted between the groups, and the group names are printed.

The "graph" mode visualizes the transitions between different states. It creates a graph in which the vertices are the states in the sequence and the edges are state transitions among these states.

The function can be called with different types of inputs: The user can specify the parameters network, startState and includeAttractorStates), in which case getPathToAttractor is called to obtain the sequence. Alternatively, the sequence can be supplied directly as a data frame in the sequence parameter.

Value

If mode="table", a matrix corresponding to the table is returned. The matrix has the genes in the rows and the states of the attractors in the columns. If sequence was supplied, this corresponds to the transposed input whose rows may be rearranged if grouping was set.

If mode="graph", an object of class igraph describing the graph for the sequence is returned.

See Also

sequenceToLaTeX, plotAttractors, attractorsToLaTeX, getPathToAttractor, getAttractorSequence, simulateSymbolicModel

Examples

## Not run: 
# load example data
data(cellcycle)

# alternative 1: supply network and start state
# and plot sequence as a table
plotSequence(network=cellcycle, 
             startState=rep(1,10), 
             includeAttractorStates="all")

# alternative 2: calculate sequence in advance
sequence <- getPathToAttractor(cellcycle, 
                               state=rep(1,10), 
                               includeAttractorStates="all")

# plot sequence as a graph
plotSequence(sequence=sequence, 
             mode="graph")

## End(Not run)