R: Plot a sequence of states

plotSequence {BoolNet} | R Documentation

## 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

    # 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")

[Package BoolNet version 2.1.4 Index]