Contexts of a context tree

This function extracts from a context tree a description of all of its contexts.

Usage

# S3 method for ctx_tree
contexts(
  ct,
  sequence = FALSE,
  reverse = FALSE,
  frequency = NULL,
  positions = FALSE,
  ...
)

# S3 method for ctx_tree_cpp
contexts(
  ct,
  sequence = FALSE,
  reverse = FALSE,
  frequency = NULL,
  positions = FALSE,
  ...
)

Arguments

ct

a context tree.

sequence

if TRUE the function returns its results as a data.frame, if FALSE (default) as a list of ctx_node objects. (see details)

reverse

logical (defaults to FALSE). See details.

frequency

specifies the counts to be included in the result data.frame. The default value of NULL does not include anything. "total" gives the number of occurrences of each context in the original sequence. "detailed" includes in addition the break down of these occurrences into all the possible states.

positions

logical (defaults to FALSE). Specify whether the positions of each context in the time series used to build the context tree should be reported in a positions column of the result data frame. The availability of the positions depends on the way the context tree was built. See details for the definition of a position.

...

additional arguments for the contexts function.

Value

A list of class contexts containing the contexts represented in this tree (as ctx_node) or a data.frame.

Details

The default behaviour of the function is to return a list of all the contexts using ctx_node objects (as returned by find_sequence()). The properties of the contexts can then be explored using adapted functions such as counts() and positions().

When sequence=TRUE the method returns a data.frame whose first column, named context, contains the contexts as vectors (i.e. the value returned by as_sequence() applied to a ctx_node object). Other columns contain context specific values specified by the additional parameters. Setting any of those parameters to a value that ask for reporting information will toggle the result type of the function to data.frame.

If frequency="total", an additional column named freq gives the number of occurrences of each context in the series used to build the tree. If frequency="detailed", one additional column is added per state in the context space. Each column records the number of times a given context is followed by the corresponding value in the original series.

Positions

A position of a context ctx in the time series x is an index value t such that the context ends with x[t]. Thus x[t+1] is after the context. For instance if x=c(0, 0, 1, 1) and ctx=c(0, 1) (in standard state order), then the position of ctx in x is 3.

State order in a context

Notice that contexts are given by default in the temporal order and not in the "reverse" order used by many VLMC research papers: older values are on the left. For instance, the context c(1, 0) is reported if the sequence 0, then 1 appeared in the time series used to build the context tree. Set reverse to TRUE for the reverse convention which is somewhat easier to relate to the way the context trees are represented by draw() (i.e. recent values at the top the tree).

See also

find_sequence() and find_sequence.covlmc() for direct access to a specific context, and contexts.ctx_tree(), contexts.vlmc() and contexts.covlmc() for concrete implementations of contexts().

Examples

dts <- sample(as.factor(c("A", "B", "C")), 100, replace = TRUE)
dts_tree <- ctx_tree(dts, max_depth = 3, min_size = 5)
## direct representation with ctx_node objects
contexts(dts_tree)
#> Contexts:
#>  A, A
#>  A, B, A
#>  B, A
#>  C, C, A
#>  C, A
#>  A, B
#>  C, B, B
#>  B, B
#>  C, C, B
#>  C, B
#>  A, C
#>  B, B, C
#>  B, C
#>  B, C, C
#>  C, C, C
#>  C, C
## data.frame format
contexts(dts_tree, sequence = TRUE)
#>    context
#> 1     A, A
#> 2  A, B, A
#> 3     B, A
#> 4  C, C, A
#> 5     C, A
#> 6     A, B
#> 7  C, B, B
#> 8     B, B
#> 9  C, C, B
#> 10    C, B
#> 11    A, C
#> 12 B, B, C
#> 13    B, C
#> 14 B, C, C
#> 15 C, C, C
#> 16    C, C
contexts(dts_tree, frequency = "total")
#>    context freq
#> 1     A, A    9
#> 2  A, B, A    5
#> 3     B, A    8
#> 4  C, C, A    6
#> 5     C, A   12
#> 6     A, B   10
#> 7  C, B, B    6
#> 8     B, B    9
#> 9  C, C, B    6
#> 10    C, B   11
#> 11    A, C   10
#> 12 B, B, C    6
#> 13    B, C   12
#> 14 B, C, C    7
#> 15 C, C, C    5
#> 16    C, C   17
contexts(dts_tree, frequency = "detailed")
#>    context freq A B C
#> 1     A, A    9 2 3 4
#> 2  A, B, A    5 2 2 1
#> 3     B, A    8 3 3 2
#> 4  C, C, A    6 1 2 3
#> 5     C, A   12 4 4 4
#> 6     A, B   10 5 2 3
#> 7  C, B, B    6 1 1 4
#> 8     B, B    9 2 1 6
#> 9  C, C, B    6 0 4 2
#> 10    C, B   11 2 6 3
#> 11    A, C   10 2 4 4
#> 12 B, B, C    6 1 0 5
#> 13    B, C   12 4 1 7
#> 14 B, C, C    7 2 3 2
#> 15 C, C, C    5 3 1 1
#> 16    C, C   17 6 6 5