Package 'ceg'

Description

This package has functionalities that allow us to create and learn Chain Event Graph (CEG) models using a Bayesian framework. It provides us with a Hierarchical Agglomerative algorithm to search the CEG model space.

Details

The package also includes several facilities for visualisations of the objects associated with a CEG. The CEG class can represent a range of relational data types, and supports arbitrary vertex, edge and graph attributes. A Chain Event Graph is a tree-based graphical model that provides a powerful graphical interface through which domain experts can easily translate a process into sequences of observed events using plain language. CEGs have been a useful class of graphical model especially to capture context-specific conditional independences.

Currently, ceg provides implementation to support the stratified family, the user will use the following classes:

• Stratified.ceg.model

• Stratified.staged.tree

• Stratified.event.tree

These classes are implemented as S4 classes and have constructor methods with the same name as the class. A plot method is also provided.

Author(s)

Maintainer: Pier Taranti [email protected]

Authors:

• Rodrigo Collazo [email protected]

See Also

Useful links:

• https://github.com/ptaranti/ceg

• Report bugs at https://github.com/ptaranti/ceg/issues

Description

AlphaEdgeInternal yields a possible objective prior distribution for each situation associated with a particular variable in the event tree.

Usage

AlphaEdgeInternal(level, stratified.event.tree, alpha)

Arguments

Value

"vector" - Dirichlet hyperparameter vector of a situation associated with a particular variable.

Description

A dataset with dummy data, based on Child Health and Development Studies (CHDS).

Usage

data(artificial.chds)

Format

a data.frame with 1500 rows and 4 categorical variables. The variables names and values are compliant with CHDS, but the values are randomly filled.

Social

High, Low

Economic

High, Low

Event

High, Average, Low

Admission

No, Yes

Examples

data(artificial.chds)

Description

Category(label) is a function that act as constructor to Category S4 object. Category S4 class contains a single slot with the category labels. It is used to construct S4 Variable objects, which, in turn, aim at being parameters in Stratified.event.tree objects manual constructions.

Usage

Category(label)

Arguments

Value

a Category S4 object

Examples

cat <- Category("category.name")

Category("category.name2")

Description

Category S4 class contains a single slot with the category label. It is used to construct Stratified.event.tree objects.

Slots

label

character

Description

Ceg.model is a S4 class whose objects represent a Chain-Event Graph (CEG) model, which is composed by a Staged Tree object and its corresponding staged structure.

Slots

staged.tree

Staged.tree S4 object

position

list

Description

Simple ceg structure to be ploted in RGraphviz. This function yields a data structure corresponding a simplified CEG to be plotted using the package Rgraphviz.

Usage

CegGraphSimple(stratified.event.tree, position, range.color = 1)

Arguments

Value

list

• $node - node attributes

• $node$nodes (vector) - set of positions.

• node$variable (vector) - it identifies the variable asscoiated with each position.

• node$color (vector) - color of each position. All positions coincident with a stage are depicted in white.

• $edge - edge attributes

• $edge$edges (list) - set of list that emanates from each position.

• edge$label (vector) - position labels.

• weight (vector) - edge weight.

Note

This function mitigates a limitation from Rgraphviz, which does not support plotting multiple edges between two nodes presenting the correct edge label for each one. The decision was to merge all edges in one, and presenting all labels in this resulting edge.#' This approach is temporary and not ideal, since the ceg is no more a multi-graph. However, the authors did not find a graphical package which provides the needed plotting features. Contributions are wellcomed.

Description

RemoveRowsWithNAandVoid remove all rows with NA and void ("") values data from a data.frame

Usage

CheckAndCleanData(data.frame)

Arguments

Value

data.frame with no void or NA values.

Description

This function creates the contigency tables associated with each variable in the event tree.

Usage

ContingencyTable(data, stratified.event.tree)

Arguments

Value

a list of matrices that represent the contigency tables associated with each variable in the event tree. The matrix corresponding to a particular variable presents the counts of each combination of the categories of the variables that precede it in the event tree according to its categories. The combinations of the categories of the upstream variables are displayed on the rows and represent the situations associated with the target variable. The categories of the target variable are represented on the columns and corresponds to each event that can unfold from a situation associated with the target variable.

Description

This function calculates the contigency table associated with a specific variable.

Usage

ContingencyTableVariable(variable, data, stratified.event.tree)

Arguments

Value

a matrix that presents the counts of each combination of the categories of the variables that precede the target variable in the event tree according to the categories of the target variable. The combinations of the categories of the upstream variables are displayed on the rows and represents a situation associated with the target variable. The categories of the target variable are represented on the columns and corresponds to each event that can unfold from a situation associated with the target variable.

Description

Dinamic.programming S4 Class

Note

Inserted fot future use

Description

Dirchlet.distribution

Slots

score

numeric.

cluster

list.

Description

Dirchlet.MPNL.distribution

Slots

score

numeric.

cluster

list.

Description

Distribution.of.probability S4 Class

Slots

score

numeric.

cluster

list.

Description

This function yields the edge labels. The edges are labeled accordingly the original data provided.

Usage

EdgeLabel(num.variable, num.situation, label)

Arguments

Value

vector - edge labels

Description

Function EdgeList genereates the list of edges of an event tree.

Usage

EdgeList(stratified.event.tree, node)

Arguments

Value

list of lists - each list component is a vector that represents the edges that emanate from a vertice.

Description

EdgeSituation identifies the edges from a situation (node). This function identifies the edges that emanate from a particular situation in an EventTree.

Usage

EdgeSituation(situation, start.situation, num.category)

Arguments

Value

list of lists - each list component is a vector that represents the edges that emanate from a vertice.

Description

Event.tree S4 object

Description

Exhaustive.model.search.algorithm S4 Class

Description

Heuristic.model.search.algorithm

Description

This function keep a lexicographical order of a vector

Usage

KeepLexOrder(ref, order.vector, score.vector)

Arguments

Description

This function identifies the edges arriving at the target level for paths that exist from the root node to each situation in the event tree that are in levels greater than the target level.

Usage

LabelStage(k, num.variable, num.situation, label.category, num.category)

Arguments

See Also

TruncatedPath

Description

This function change a list of vectors in a vector.

Usage

ListToVector(x, n)

Arguments

Value

vector

Description

Merge labels of multiple edges in order to plot them all.

Usage

MergeLabels(edge.list, edge, level)

Arguments

Value

list merged labels associated with a specific position v1.

Note

This function mitigates a limitation from Rgraphviz, since it is not possible to plot multiple edges between two nodes presenting the correct edge label for each one. The authors did not find a graphical package providing this capability. Contributions are wellcomed.

Description

Model.search.algorithm

Description

Multinomial.distribution

Slots

score

numeric.

cluster

list.

Description

This function yields the node colors.

Usage

NodeColor(num.variable, num.situation, num.category, stage.structure,
  range.color)

Arguments

Value

vector - node colors

Description

This function yields the node labels. The nodes are labeled accordingly, to indicate diferente positions.

Usage

NodeLabel(num.variable, num.situation, num.category, label)

Arguments

Value

vector - node labels

Description

This function genereates the nodes of an event tree.

Usage

NodeSet(tree)

Arguments

Value

vector

Description

This function calculates the best stage configuration of a hyperstage associated with a specific variable of time-slice t_0 or t_k, k>=1, using the oahc algorithm (oahc - Optimised Agglomerative Hierarchical Clustering)

Usage

OAHC(level, prior.distribution, contingency.table, tree)

Arguments

Value

a OAHC S4 object

See Also

SingleScore, PairwiseScore, SingleReorder, NaReorder, KeepLexOrder

Description

@include heuristic_model_search_algorithm.R

Slots

score

numeric

cluster

list

Description

The PairwisePosition function identifies if two situations are in the same position given that they are in the same stage.

Usage

PairwisePosition(pair.situation, num.category, pos.next.level)

Arguments

Value

boolean

Description

This Method is used to plot a chain event graph from a Stratified.ceg.model S4 object. The current ceg package implementation depends on Rgraphviz package from Bioconductor to draw the CEG graph.

Usage

## S4 method for signature 'Stratified.ceg.model,ANY'
plot(x)

Arguments

Value

the plot and also a pdf version is saved in the working directory.

Examples

plot(scm)

Description

Method to plot a Stratified.event.tree S4 object. The current ceg package implementation depends on Rgraphviz package from Bioconductor for plotting.

Usage

## S4 method for signature 'Stratified.event.tree,ANY'
plot(x)

Arguments

Value

the plot and also a pdf version is saved in the working directory.

Examples

plot(set)

Description

Method to plot a Staged.tree S4 object. The current package ceg depends on Rgraphviz package from Bioconductor to draw graphs.

Usage

## S4 method for signature 'Stratified.staged.tree,ANY'
plot(x)

Arguments

Value

the plot. A pdf version is also saved in the working directory.

Examples

plot(sst)

Description

This function obtains the position structure associated with a particular variable of a CEG.

Usage

PositionLevel(stage.list, num.category, num.situation.next,
  pos.next.level = list())

Arguments

Value

list of lists - The first list level identifies a stage 'i' and the second list level identifies the positions associated with this stage 'i'.

See Also

PositionVector, PositionStage and PairwisePosition

Description

PositionStage function yields the position structure associated with a particular stage of a CEG.

Usage

PositionStage(stage.vector, num.category, pos.next.level)

Arguments

Value

list of vector - Each vector identifies a position.

See Also

PairwisePosition

Description

PositionVector function rewrites a position structure associated with a particular variable: from a list to a vector.

Usage

PositionVector(num.situation, pos.list)

Arguments

Value

vector

Description

Posterior.distribution

Description

Prior.distribution

Description

PriorDistribution initialises the prior distributions under the conservative and uniform assumptions for the hyperparameter 'alpha' over the event tree.

Usage

PriorDistribution(stratified.event.tree, alpha)

Arguments

Value

prior is a list of matrices. Each matrix is a collection of vectors that correspond to a prior for each situation associated with a particular variable.

See Also

PriorVariable

Description

The function PriorVariable yields the prior distributions for all situations associated with a particular variable in the event tree.

Usage

PriorVariable(ref, alpha.edge)

Arguments

Value

a matrix. Each row represents the Dirichlet hyperparameter vector of a situation associated with a particular variable in the event tree.

See Also

Prior.distribution and AlphaEdgeInternal

Description

A Stratified.ceg.model S4 object, generated using the command scm <- Stratified.ceg.model(sst)

Usage

data(scm)

Format

a Stratified.ceg.model S4 object

Examples

data(scm)

Description

A Stratified.event.tree S4 object, generated using the command set <- Stratified.event.tree(artificial.chds)

Usage

data(set)

Format

a Stratified.event.tree S4 object

Examples

data(set)

Description

A Stratified.event.tree S4 object, generated using manual input.
See Stratified.event.tree documentation examples.

Usage

data(set)

Format

a Stratified.event.tree S4 object

Examples

data(set.manual)

Description

A Stratified.staged.tree S4 object, generated using the command sst <- Stratified.staged.tree(artificial.chds)

Usage

data(sst)

Format

a Stratified.staged.tree S4 object

Examples

data(sst)

Description

A staged tree is an event tree embellished with colours using a probabilistic measure. Two situations are said to be in the same stage if they have equivalent probabilistic space and identical conditional probabilities. Each stage is associated with a different colour.

Slots

event.tree

Event.tree.

Description

S3 function to friendly construct S4 Stratified.ceg.model.

Usage

Stratified.ceg.model(stratified.staged.tree)

Arguments

Value

a Stratified.ceg.model S4 object.

Examples

scm <- Stratified.ceg.model(sst)

Description

The Stratified.ceg.model is a S4 class that extends Ceg.model. The object represents a CEG model derived from its supporting Stratified.staged.tree using some graphical transformation rules.

Description

Constructor method to Stratified.event.tree S4 objects. It accepts different sets for parameters types.

Usage

Stratified.event.tree(x, ...)

## S4 method for signature 'missing'
Stratified.event.tree(x)

## S4 method for signature 'ANY'
Stratified.event.tree(x, ...)

## S4 method for signature 'data.frame'
Stratified.event.tree(x = "data.frame")

## S4 method for signature 'list'
Stratified.event.tree(x = "list")

Arguments

Value

a Stratified.event.tree S4 object

Note

A Stratified.event.tree may be manualy created (see examles)
A call to Stratified.event.tree( ) with no parameters will return an error message for missing argument.
A call to Stratified.event.tree(x, ...), x not being a data.frame or a list, will return an error message.

Examples

set <- Stratified.event.tree(artificial.chds)

set.manual <- Stratified.event.tree(list(Variable("age",list(Category("old"),
Category("medium"), Category("new"))),Variable("state", list(Category("solid"),
Category("liquid"), Category("steam"))), Variable("costumer",
list(Category("good"), Category("average"), Category("very bad"),
Category("bad")))))

Description

An event tree is called stratified if the set of events that unfold from all situations, which are at the same distance of edges from the initial situation, are identical.

Description

Constructor method to Stratified.staged.tree S4 objects. It accepts different sets for parameters types.

Usage

Stratified.staged.tree(x, y, z, ...)

## S4 method for signature 'missing,ANY,ANY'
Stratified.staged.tree(x, y, z, ...)

## S4 method for signature 'ANY,ANY,ANY'
Stratified.staged.tree(x, y, z, ...)


  ## S4 method for signature 'data.frame,numeric,numeric'
Stratified.staged.tree(x = "data.frame",
  y = 1L, z = 0L)


  ## S4 method for signature 'data.frame,numeric,missing'
Stratified.staged.tree(x = "data.frame",
  y = 1L)


  ## S4 method for signature 'data.frame,missing,missing'
Stratified.staged.tree(x = "data.frame")


  ## S4 method for signature 'Stratified.event.tree,list,ANY'
Stratified.staged.tree(x = "Stratified.event.tree",
  y = "list")

Arguments

Value

a Stratified.staged.tree S4 object

Note

The implementation admits providing the three arguments, or the first two, or even only the data.frame.
The default variable order is as in the data.frame and the default alpha is 1L.
To manualy create a stratified.event.tree from a stratified.event.tree:

1st

plot the stratified.event.tree - plot(set)

2nd

Looking the graph, you can create the stage structure, such as: stage.structure <- list(list(c(2,3)), list(c(4,7,12),c(5,8,9)))

3rd

Finally you can create your Stratified.event.tree: st.manual<- Stratified.staged.tree(set, stage.structure)

A call to Stratified.staged.tree( ) with no parameters will return an error message for missing argument.
A call to Stratified.staged.tree(x, ...), x not being a data.frame or a Event.tree, will return an error message.

Examples

sst <- Stratified.staged.tree(artificial.chds)

stt.manual <- Stratified.staged.tree(set.manual,
list(list(c(2,3)), list(c(4,7,12),c(5,8,9))))

Description

A stratified staged tree is a staged tree whose supporting event tree is stratified and all vertices which are in the same stage are also at the same distance of edges from the root.

Slots

event.tree

Stratified.event.tree. An stratified event tree is an event tree whose set of events that unfold from all situations, which are at the same distance of edges from the initial situation, are identical.

situation

list.

contingency.table

list of matrices that represent the contigency tables associated with each variable in the event tree.

stage.structure

list in which each component is a list associated with a variable in the staged tree that has the following data structure:

• $score - numeric. This is the logarithmic form of the marginal likelihood associated with a particular variable.

• $cluster - list whose components are vectors. Each vector represents a stage associated with a particular variable.

stage.probability

list in which each component is a list associated with a variable in the staged tree. Each component of this sublist is a vector that represents the probability distribution associated with a particular stage of the target variable.

prior.distribution

list of matrices. Each matrix is a collection of vectors that correspond t a prior distribution for each situation associated with a particular variable.

posterior.distribution

list of matrices. Each matrix is a collection of vectors that correspond t a prior distribution for each situation associated with a particular variable.

model.score

numeric. This is the logarithmic form of the marginal likelihood.

Description

This function obtains the position structure associated with a stratified CEG.

Usage

StratifiedCegPosition(stage, num.category, num.situation)

Arguments

Value

list of lists

• First list level identifies a variable 'v'.

• Second list level identifies a stage 'a' associated with a variable 'v'.

• The third list level identifies the positions associated with a stage 'a' .

@seealso PositionLevel, PositionVector, PositionStage, PairwisePosition

Description

StratifiedEventTreeGraph

Usage

StratifiedEventTreeGraph(event.tree)

Arguments

Description

A function to produce the data structure needed to plot Event and Staged trees using RGraphviz.

Usage

TreeGraph(tree, solution = list(), name = c(), range.color = 1)

Arguments

Value

list:

• $node - node attributes

  • $node$nodes (vector) - set of situations.

  • node$label (vector) - it identifies the variable asscoiated with each position.

  • node$color (vector) - color of each situation. All situations coincident with a stage are depicted in black.

• $edge - edge attributes

  • $edge$edges (list) - set of list that emanates from each situation.

  • edge$label (vector) - edge labels.

Description

This internal function yields a vector that contains the edges arriving at situations associated with a particular variable for all paths that emanate from the root node and pass through these situations in the event tree.

Usage

TruncatedPath(ref, k, var, num.category, num.situation, label.category)

Arguments

Description

Variable(name,categories) is a function that act as constructor to Variable S4 object. Variable S4 class contains two slots with the Variable name and a list of Categories. It is used to construct Stratified.vent.tree objects.

Usage

Variable(name, categories)

Arguments

Value

a Variable S4 object

Examples

var <- Variable("variable.name", list(Category("cat1"), Category("cat2"),
Category("cat3")))

Description

Variable S4 class contains two slots with the Variable name and a list of Categories. It is used to construct Stratified.vent.tree objects.

Slots

name

character.

categories

list of Category S4 objects.