Package 'mixvlmc'

Description

Estimates Variable Length Markov Chains (VLMC) models and VLMC with covariates models from discrete sequences. Supports model selection via information criteria and simulation of new sequences from an estimated model. See Bühlmann, P. and Wyner, A. J. (1999) doi:10.1214/aos/1018031204 for VLMC and Zanin Zambom, A., Kim, S. and Lopes Garcia, N. (2022) doi:10.1111/jtsa.12615 for VLMC with covariates.

Package options

Mixvlmc uses the following options():

• mixvlmc.maxit: maximum number of iterations in model fitting for covlmc()

• mixvlmc.predictive: specifies the computing engine used for model fitting for covlmc(). Two values are supported:

  • "glm" (default value): covlmc() uses stats::glm() with a binomial link (stats::binomial()) for a two values state space, and VGAM::vglm() with a multinomial link (VGAM::multinomial()) for a state space with three or more values;

  • "multinom": covlmc() uses nnet::multinom() in all cases.

  The first option "glm" is recommended as both stats::glm() and VGAM::vglm() are able to detect and deal with degeneracy in the data set.

• mixvlmc.backend: specifies the implementation used for the context tree construction in ctx_tree(), vlmc() and tune_vlmc(). Two values are supported:

  • "R" (default value): this corresponds to the original almost pure R implementation.

  • "C++": this corresponds to the experimental C++ implementation. This version is significantly faster than the R version, but is still considered experimental.

• mixvlmc.charset: specifies the collection of characters used to display context trees in "ascii art" when using the "text" format for draw() and related functions. Two values are supported:

  • "ascii": the collection uses only standard ASCII characters and should be compatible with all environments;

  • "utf8": the collection uses UTF-8 symbols and needs a compatible display. At loading the option is set based on a call to cli::is_utf8_output(). It defaults to "utf8" is this encoding is supported.

Author(s)

Maintainer: Fabrice Rossi [email protected] (ORCID) [copyright holder]

Other contributors:

• Hugo Le Picard [email protected] (ORCID) [contributor]

• Guénolé Joubioux [email protected] [contributor]

See Also

Useful links:

• https://github.com/fabrice-rossi/mixvlmc

• https://fabrice-rossi.github.io/mixvlmc/

• Report bugs at https://github.com/fabrice-rossi/mixvlmc/issues

Description

This generic function converts an object into a covlmc.

Usage

as_covlmc(x, ...)

## S3 method for class 'tune_covlmc'
as_covlmc(x, ...)

Arguments

Value

a covlmc

See Also

tune_covlmc()

Examples

## conversion from the results of tune_covlmc
pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
rdts_best_model_tune <- tune_covlmc(rdts, rdts_cov)
rdts_best_model <- as_covlmc(rdts_best_model_tune)
draw(rdts_best_model)

Description

This function returns the sequence represented by the node object.

Usage

as_sequence(node, reverse)

Arguments

Value

the sequence represented by the node object, a vector

Examples

rdts <- c("A", "B", "C", "A", "A", "B", "B", "C", "C", "A")
rdts_tree <- ctx_tree(rdts, max_depth = 3)
res <- find_sequence(rdts_tree, "A")
as_sequence(res)

Description

This generic function converts an object into a vlmc.

Usage

as_vlmc(x, ...)

## S3 method for class 'ctx_tree'
as_vlmc(x, alpha, cutoff, ...)

## S3 method for class 'tune_vlmc'
as_vlmc(x, ...)

Arguments

Details

This function converts a context tree into a VLMC. If alpha or cutoff is specified, it is used to reduce the complexity of the tree as in a direct call to vlmc() (prune()).

Value

a vlmc

See Also

ctx_tree()

tune_vlmc()

Examples

## conversion from a context tree
rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3)
draw(rdts_ctree)
rdts_vlmc <- as_vlmc(rdts_ctree)
class(rdts_vlmc)
draw(rdts_vlmc)
## conversion from the result of tune_vlmc
rdts <- sample(as.factor(c("A", "B", "C")), 100, replace = TRUE)
tune_result <- tune_vlmc(rdts)
tune_result
rdts_best_vlmc <- as_vlmc(tune_result)
draw(rdts_best_vlmc)

Description

This generic function converts an object into a vlmc.

Usage

## S3 method for class 'ctx_tree_cpp'
as_vlmc(x, alpha, cutoff, ...)

Arguments

Details

This function converts a context tree into a VLMC. If alpha or cutoff is specified, it is used to reduce the complexity of the tree as in a direct call to vlmc() (prune()).

Value

a vlmc

See Also

ctx_tree()

tune_vlmc()

Examples

## conversion from a context tree
rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3, backend = "C++")
draw(rdts_ctree)
rdts_vlmc <- as_vlmc(rdts_ctree)
class(rdts_vlmc)
draw(rdts_vlmc)

Description

This function prepares a plot of the results of tune_covlmc() using ggplot2. The result can be passed to print() to display the result.

Usage

## S3 method for class 'tune_covlmc'
autoplot(object, ...)

Arguments

Details

The graphical representation proposed by this function is complete, while the one produced by plot.tune_covlmc() is minimalistic. We use here the faceting capabilities of ggplot2 to combine on a single graphical representation the evolution of multiple characteristics of the VLMC during the pruning process, while plot.tune_covlmc() shows only the selection criterion or the log likelihood. Each facet of the resulting plot shows a quantity as a function of the cut off expressed in quantile or native scale.

Value

a ggplot object

Examples

pc <- powerconsumption[powerconsumption$week %in% 10:12, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
rdts_best_model_tune <- tune_covlmc(rdts, rdts_cov, criterion = "AIC")
covlmc_plot <- ggplot2::autoplot(rdts_best_model_tune)
print(covlmc_plot)

Description

This function prepares a plot of the results of tune_vlmc() using ggplot2. The result can be passed to print() to display the result.

Usage

## S3 method for class 'tune_vlmc'
autoplot(object, cutoff = c("quantile", "native"), ...)

Arguments

Details

The graphical representation proposed by this function is complete, while the one produced by plot.tune_vlmc() is minimalistic. We use here the faceting capabilities of ggplot2 to combine on a single graphical representation the evolution of multiple characteristics of the VLMC during the pruning process, while plot.tune_vlmc() shows only the selection criterion or the log likelihood. Each facet of the resulting plot shows a quantity as a function of the cut off expressed in quantile or native scale.

Value

a ggplot object

Examples

pc <- powerconsumption[powerconsumption$week %in% 10:11, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
rdts_best_model_tune <- tune_vlmc(rdts, criterion = "BIC")
vlmc_plot <- ggplot2::autoplot(rdts_best_model_tune)
print(vlmc_plot)
## simple post customisation
print(vlmc_plot + ggplot2::geom_point())

Description

This function returns a list of ASCII characters used to fine tune the draw() function behaviour when it is used with format="text". It can be used as is or customised using its parameters.

Usage

charset_ascii(
  root = "*",
  first_node = "+",
  next_node = "'",
  final_node = "'",
  vbranch = "|",
  hbranch = "--",
  open_ct = "(",
  close_ct = ")",
  level_sep = " ~ ",
  time_sep = " | ",
  intercept = "(I)",
  intercept_sep = " & ",
  open_p_value = "<",
  close_p_value = ">",
  open_model = "[",
  close_model = "]"
)

Arguments

Value

a list

See Also

draw(), charset_utf8().

Examples

charset_ascii(root = "x")

Description

This function returns a list of UTF-8 characters and symbols used to fine tune the draw() function behaviour when it is used with format="text". It can be used as is or customised using its parameters.

Usage

charset_utf8(
  root = "▪",
  first_node = "├",
  next_node = "├",
  final_node = "└",
  vbranch = "│",
  hbranch = "─",
  open_ct = "(",
  close_ct = ")",
  level_sep = " ~ ",
  time_sep = " ⁞ ",
  intercept = "(I)",
  intercept_sep = " • ",
  open_p_value = "‹",
  close_p_value = "›",
  open_model = "[",
  close_model = "]"
)

Arguments

Value

a list

See Also

draw(), charset_ascii().

Examples

charset_utf8(root = "\u27E1")

Description

This function returns a list (possibly empty) of ctx_node objects. Each object represents one of the children of the node represented by the node parameter.

Usage

children(node)

## S3 method for class 'ctx_node'
children(node)

## S3 method for class 'ctx_node_cpp'
children(node)

Arguments

Details

Each node of a context tree represents a sequence. When find_sequence() is called with success, the returned object represents the corresponding node in the context tree. If this node has no child, the present function returns an empty list. When the node has at least one child, the function returns a list with one value for each element in the state space (see states()). The value is NULL if the corresponding child is empty, while it is a ctx_node object when the child is present. Each ctx_node object is associated to the sequence obtained by adding to the past of the sequence represented by node an observation of the associated state (this corresponds to an extension to the left of the sequence in temporal order).

Value

a list of ctx_node objects, see details.

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3)
ctx_00 <- find_sequence(rdts_ctree, c(0, 0))
## this context can only be extended in the past by 1:
children(ctx_00)
ctx_10 <- find_sequence(rdts_ctree, c(1, 0))
## this context can be extended by both states
children(ctx_10)
## C++ backend
rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3, backend = "C++")
ctx_00 <- find_sequence(rdts_ctree, c(0, 0))
## this context can only be extended in the past by 1:
children(ctx_00)
ctx_10 <- find_sequence(rdts_ctree, c(1, 0))
## this context can be extended by both states
children(ctx_10)

Description

This function returns the number of distinct contexts in a context tree.

Usage

context_number(ct)

Arguments

Value

the number of contexts of the tree.

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3)
# should be 8
context_number(rdts_ctree)

Description

This function returns the total number of contexts of a VLMC with covariates.

Usage

## S3 method for class 'covlmc'
context_number(ct)

Arguments

Value

the number of contexts present in the VLMC with covariates.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
dts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
dts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(dts, dts_cov, min_size = 10)
# should be 3
context_number(m_cov)

Description

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

Usage

contexts(ct, sequence = FALSE, reverse = FALSE, ...)

Arguments

Details

The default behaviour consists in returning a list of all the contexts contained in the tree using ctx_node objects (as returned by e.g. find_sequence()) (with type="list"). The properties of the contexts can then be explored using adapted functions such as counts() and positions(). The result list is of class contexts. 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 which depend on the actual class of the tree and on additional parameters. In all implementations of contexts(), setting the additional parameters to any no default value leads to a data.frame result.

Value

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

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

rdts <- sample(as.factor(c("A", "B", "C")), 100, replace = TRUE)
rdts_tree <- ctx_tree(rdts, max_depth = 3, min_size = 5)
contexts(rdts_tree)
contexts(rdts_tree, TRUE, TRUE)

Description

This function returns the different contexts present in a VLMC with covariates, possibly with some associated data.

Usage

## S3 method for class 'covlmc'
contexts(
  ct,
  sequence = FALSE,
  reverse = FALSE,
  frequency = NULL,
  positions = FALSE,
  local = FALSE,
  metrics = FALSE,
  model = NULL,
  hsize = FALSE,
  merging = FALSE,
  ...
)

Arguments

Details

The default behaviour of the function is to return a list of all the contexts using ctx_node_covlmc objects (as returned by find_sequence.covlmc()). The properties of the contexts can then be explored using adapted functions such as counts(), covariate_memory(), cutoff.ctx_node(), metrics.ctx_node(), model(), merged_with() 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.

See contexts.ctx_tree() for details about the frequency parameter. When model is non NULL, the resulting data.frame contains the models associated to each context (either the full R model or its coefficients). Other columns are added is the corresponding parameters are set to TRUE.

Value

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

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

pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(0, median(pc$active_power), max(pc$active_power))
dts <- cut(pc$active_power, breaks = breaks)
dts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(dts, dts_cov, min_size = 5)
## direct representation with ctx_node_covlmc objects
m_cov_ctxs <- contexts(m_cov)
m_cov_ctxs
sapply(m_cov_ctxs, covariate_memory)
sapply(m_cov_ctxs, is_merged)
sapply(m_cov_ctxs, model)
## data.frame interface
contexts(m_cov, model = "coef")
contexts(m_cov, model = "full", hsize = TRUE)

Description

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

Usage

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

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

Arguments

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.

Value

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

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

rdts <- sample(as.factor(c("A", "B", "C")), 100, replace = TRUE)
rdts_tree <- ctx_tree(rdts, max_depth = 3, min_size = 5)
## direct representation with ctx_node objects
contexts(rdts_tree)
## data.frame format
contexts(rdts_tree, sequence = TRUE)
contexts(rdts_tree, frequency = "total")
contexts(rdts_tree, frequency = "detailed")

Description

This function extracts all the contexts from a fitted VLMC, possibly with some associated data.

Usage

## S3 method for class 'vlmc'
contexts(
  ct,
  sequence = FALSE,
  reverse = FALSE,
  frequency = NULL,
  positions = FALSE,
  local = FALSE,
  cutoff = NULL,
  metrics = FALSE,
  ...
)

## S3 method for class 'vlmc_cpp'
contexts(
  ct,
  sequence = FALSE,
  reverse = FALSE,
  frequency = NULL,
  positions = FALSE,
  local = FALSE,
  cutoff = NULL,
  metrics = FALSE,
  ...
)

Arguments

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(), cutoff.ctx_node(), metrics.ctx_node() 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.

The frequency parameter is described in details in the documentation of contexts.ctx_tree(). When cutoff is non NULL, the resulting data.frame contains a cutoff column with the cut off values, either in quantile or in native scale. See cutoff.vlmc() and prune.vlmc() for the definitions of cut off values and of the two scales.

Value

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

Cut off values

The cut off values reported by contexts.vlmc can be different from the ones reported by cutoff.vlmc() for three reasons:

1. cutoff.vlmc() reports only useful cut off values, i.e., cut off values that should induce a simplification of the VLMC when used in prune(). This exclude cut off values associated to simple contexts that are smaller than the ones of their descendants in the context tree. Those values are reported by context.vlmc.

2. context.vlmc reports only cut off values of actual contexts, while cutoff.vlmc() reports cut off values for all nodes of the context tree.

3. values are not modified to induce pruning, contrarily to the default behaviour of cutoff.vlmc()

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

rdts <- sample(as.factor(c("A", "B", "C")), 100, replace = TRUE)
model <- vlmc(rdts, alpha = 0.5)
## direct representation with ctx_node objects
model_ctxs <- contexts(model)
model_ctxs
sapply(model_ctxs, cutoff, scale = "quantile")
sapply(model_ctxs, cutoff, scale = "native")
sapply(model_ctxs, function(x) metrics(x)$accuracy)
## data.frame format
contexts(model, frequency = "total")
contexts(model, cutoff = "quantile")
contexts(model, cutoff = "native", metrics = TRUE)

Description

This function reports the number of occurrences of the sequence represented by node in the original time series used to build the associated context tree (not including a possible final occurrence not followed by any value at the end of the original time series). In addition if frequency=="detailed", the function reports the frequencies of each of the possible value of the time series when they appear just after the sequence.

Usage

counts(node, frequency = c("detailed", "total"), local = FALSE)

## S3 method for class 'ctx_node'
counts(node, frequency = c("detailed", "total"), local = FALSE)

## S3 method for class 'ctx_node_cpp'
counts(node, frequency = c("detailed", "total"), local = FALSE)

Arguments

Value

either an integer when frequency="total" which gives the total number of occurrences of the sequence represented by node or a data.frame with a total column with the same value and a column for each of the possible value of the original time series, reporting counts in each column (see the description above).

See Also

contexts() and contexts.ctx_tree()

Examples

rdts <- sample(as.factor(c("A", "B", "C")), 100, replace = TRUE)
rdts_tree <- ctx_tree(rdts, max_depth = 3, min_size = 5)
subseq <- find_sequence(rdts_tree, factor(c("A", "A"), levels = c("A", "B", "C")))
if (!is.null(subseq)) {
  counts(subseq)
}

Description

This function return the longest covariate memory used by a VLMC with covariates.

Usage

covariate_depth(model)

Arguments

Value

the longest covariate memory of this model

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
m_nocovariate <- vlmc(rdts)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 10)
covariate_depth(m_cov)

Description

This function returns the length of the memory of a COVLMC context represented by a ctx_node_covlmc object.

Usage

covariate_memory(node)

Arguments

Value

the memory length, an integer

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 10)
ctxs <- contexts(m_cov)
## get all the memory lengths
sapply(ctxs, covariate_memory)

Description

This function fits a Variable Length Markov Chain with covariates (coVLMC) to a discrete time series coupled with a time series of covariates.

Usage

covlmc(
  x,
  covariate,
  alpha = 0.05,
  min_size = 5L,
  max_depth = 100L,
  keep_data = TRUE,
  control = covlmc_control(...),
  ...
)

Arguments

Details

The model is built using the algorithm described in Zanin Zambom et al. As for the vlmc() approach, the algorithm builds first a context tree (see ctx_tree()). The min_size parameter is used to compute the actual number of observations per context in the growing phase of the tree. It is computed as min_size*(1+ncol(covariate)*d)*(s-1) where d is the length of the context (a.k.a. the depth in the tree) and s is the number of states. This corresponds to ensuring min_size observations per parameter of the logistic regression during the estimation phase.

Then logistic models are adjusted in the leaves at the tree: the goal of each logistic model is to estimate the conditional distribution of the next state of the times series given the context (the recent past of the time series) and delayed versions of the covariates. A pruning strategy is used to simplified the models (mainly to reduce the time window associated to the covariates) and the tree itself.

Parameters specified by control are used to fine tune the behaviour of the algorithm.

Value

a fitted covlmc model.

Logistic models

By default, covlmc uses two different computing engines for logistic models:

• when the time series has only two states, covlmc uses stats::glm() with a binomial link (stats::binomial());

• when the time series has at least three states, covlmc use VGAM::vglm() with a multinomial link (VGAM::multinomial()).

Both engines are able to detect degenerate cases and lead to more robust results that using nnet::multinom(). It is nevertheless possible to replace stats::glm() and VGAM::vglm() with nnet::multinom() by setting the global option mixvlmc.predictive to "multinom" (the default value is "glm"). Notice that while results should be comparable, there is no guarantee that they will be identical.

References

• Bühlmann, P. and Wyner, A. J. (1999), "Variable length Markov chains." Ann. Statist. 27 (2) 480-513 doi:10.1214/aos/1018031204

• Zanin Zambom, A., Kim, S. and Lopes Garcia, N. (2022), "Variable length Markov chain with exogenous covariates." J. Time Ser. Anal., 43 (2) 312-328 doi:10.1111/jtsa.12615

See Also

cutoff.covlmc() and prune.covlmc() for post-pruning.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power,
  probs = c(1 / 3, 2 / 3, 1)
)))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 15)
draw(m_cov)
withr::with_options(
  list(mixvlmc.predictive = "multinom"),
  m_cov_nnet <- covlmc(rdts, rdts_cov, min_size = 15)
)
draw(m_cov_nnet)

Description

This function creates a list with parameters used to fine tune the coVLMC fitting algorithm.

Usage

covlmc_control(pseudo_obs = 1)

Arguments

Details

pseudo_obs is used to regularize the probability estimations when a context is only observed followed by always the same state. Transition probabilities are computed after adding pseudo_obs pseudo observations of each of the states (including the observed one). This corresponds to a Bayesian posterior mean estimation with a Dirichlet prior.

Value

a list.

Examples

rdts <- rep(c(0, 1), 100)
rdts_cov <- data.frame(y = rep(0, length(rdts)))
default_model <- covlmc(rdts, rdts_cov)
contexts(default_model, type = "data.frame", model = "coef")$coef
control <- covlmc_control(pseudo_obs = 10)
model <- covlmc(rdts, rdts_cov, control = control)
contexts(model, type = "data.frame", model = "coef")$coef

Description

This function fits a Variable Length Markov Chain with covariates (coVLMC) to a discrete time series coupled with a time series of covariates.

Usage

## Default S3 method:
covlmc(
  x,
  covariate,
  alpha = 0.05,
  min_size = 5L,
  max_depth = 100L,
  keep_data = TRUE,
  control = covlmc_control(...),
  ...
)

Arguments

Details

The model is built using the algorithm described in Zanin Zambom et al. As for the vlmc() approach, the algorithm builds first a context tree (see ctx_tree()). The min_size parameter is used to compute the actual number of observations per context in the growing phase of the tree. It is computed as min_size*(1+ncol(covariate)*d)*(s-1) where d is the length of the context (a.k.a. the depth in the tree) and s is the number of states. This corresponds to ensuring min_size observations per parameter of the logistic regression during the estimation phase.

Then logistic models are adjusted in the leaves at the tree: the goal of each logistic model is to estimate the conditional distribution of the next state of the times series given the context (the recent past of the time series) and delayed versions of the covariates. A pruning strategy is used to simplified the models (mainly to reduce the time window associated to the covariates) and the tree itself.

Parameters specified by control are used to fine tune the behaviour of the algorithm.

Value

a fitted covlmc model.

Logistic models

By default, covlmc uses two different computing engines for logistic models:

• when the time series has only two states, covlmc uses stats::glm() with a binomial link (stats::binomial());

• when the time series has at least three states, covlmc use VGAM::vglm() with a multinomial link (VGAM::multinomial()).

Both engines are able to detect degenerate cases and lead to more robust results that using nnet::multinom(). It is nevertheless possible to replace stats::glm() and VGAM::vglm() with nnet::multinom() by setting the global option mixvlmc.predictive to "multinom" (the default value is "glm"). Notice that while results should be comparable, there is no guarantee that they will be identical.

References

• Bühlmann, P. and Wyner, A. J. (1999), "Variable length Markov chains." Ann. Statist. 27 (2) 480-513 doi:10.1214/aos/1018031204

• Zanin Zambom, A., Kim, S. and Lopes Garcia, N. (2022), "Variable length Markov chain with exogenous covariates." J. Time Ser. Anal., 43 (2) 312-328 doi:10.1111/jtsa.12615

See Also

cutoff.covlmc() and prune.covlmc() for post-pruning.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power,
  probs = c(1 / 3, 2 / 3, 1)
)))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 15)
draw(m_cov)
withr::with_options(
  list(mixvlmc.predictive = "multinom"),
  m_cov_nnet <- covlmc(rdts, rdts_cov, min_size = 15)
)
draw(m_cov_nnet)

Description

This function fits a Variable Length Markov Chain with covariates (coVLMC) to a discrete time series coupled with a time series of covariates.

Usage

## S3 method for class 'dts'
covlmc(
  x,
  covariate,
  alpha = 0.05,
  min_size = 5L,
  max_depth = 100L,
  keep_data = TRUE,
  control = covlmc_control(...),
  ...
)

Arguments

Details

The model is built using the algorithm described in Zanin Zambom et al. As for the vlmc() approach, the algorithm builds first a context tree (see ctx_tree()). The min_size parameter is used to compute the actual number of observations per context in the growing phase of the tree. It is computed as min_size*(1+ncol(covariate)*d)*(s-1) where d is the length of the context (a.k.a. the depth in the tree) and s is the number of states. This corresponds to ensuring min_size observations per parameter of the logistic regression during the estimation phase.

Then logistic models are adjusted in the leaves at the tree: the goal of each logistic model is to estimate the conditional distribution of the next state of the times series given the context (the recent past of the time series) and delayed versions of the covariates. A pruning strategy is used to simplified the models (mainly to reduce the time window associated to the covariates) and the tree itself.

Parameters specified by control are used to fine tune the behaviour of the algorithm.

Value

a fitted covlmc model.

Logistic models

By default, covlmc uses two different computing engines for logistic models:

• when the time series has only two states, covlmc uses stats::glm() with a binomial link (stats::binomial());

• when the time series has at least three states, covlmc use VGAM::vglm() with a multinomial link (VGAM::multinomial()).

Both engines are able to detect degenerate cases and lead to more robust results that using nnet::multinom(). It is nevertheless possible to replace stats::glm() and VGAM::vglm() with nnet::multinom() by setting the global option mixvlmc.predictive to "multinom" (the default value is "glm"). Notice that while results should be comparable, there is no guarantee that they will be identical.

References

• Bühlmann, P. and Wyner, A. J. (1999), "Variable length Markov chains." Ann. Statist. 27 (2) 480-513 doi:10.1214/aos/1018031204

• Zanin Zambom, A., Kim, S. and Lopes Garcia, N. (2022), "Variable length Markov chain with exogenous covariates." J. Time Ser. Anal., 43 (2) 312-328 doi:10.1111/jtsa.12615

See Also

cutoff.covlmc() and prune.covlmc() for post-pruning.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
power_dts <- dts(cut(pc$active_power, breaks = c(0, quantile(pc$active_power,
  probs = c(1 / 3, 2 / 3, 1)
))))
power_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(power_dts, power_cov, min_size = 15)
draw(m_cov)

Description

This function builds a context tree for a time series.

Usage

ctx_tree(
  x,
  min_size = 2L,
  max_depth = 100L,
  keep_position = TRUE,
  backend = getOption("mixvlmc.backend", "R"),
  ...
)

Arguments

Details

The tree represents all the sequences of symbols/states of length smaller than max_depth that appear at least min_size times in the time series and stores the frequencies of the states that follow each context. Optionally, the positions of the contexts in the time series can be stored in the tree.

Value

a context tree (of class that inherits from ctx_tree).

Back ends

Two back ends are available to compute context trees:

• the "R" back end represents the tree in pure R data structures (nested lists) that be easily processed further in pure R (C++ helper functions are used to speed up the construction).

• the "C++" back end represents the tree with C++ classes. This back end is considered experimental. The tree is built with an optimised suffix tree algorithm which speeds up the construction by at least a factor 10 in standard settings. As the tree is kept outside of R direct reach, context trees built with the C++ back end must be restored after a saveRDS()/readRDS() sequence. This is done automatically by recomputing completely the context tree.

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
## get all contexts of length 2
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 2)
draw(rdts_ctree)

Description

This function builds a context tree for a time series.

Usage

## Default S3 method:
ctx_tree(
  x,
  min_size = 2L,
  max_depth = 100L,
  keep_position = TRUE,
  backend = getOption("mixvlmc.backend", "R"),
  ...
)

Arguments

Details

The tree represents all the sequences of symbols/states of length smaller than max_depth that appear at least min_size times in the time series and stores the frequencies of the states that follow each context. Optionally, the positions of the contexts in the time series can be stored in the tree.

Value

a context tree (of class that inherits from ctx_tree).

Back ends

Two back ends are available to compute context trees:

• the "R" back end represents the tree in pure R data structures (nested lists) that be easily processed further in pure R (C++ helper functions are used to speed up the construction).

• the "C++" back end represents the tree with C++ classes. This back end is considered experimental. The tree is built with an optimised suffix tree algorithm which speeds up the construction by at least a factor 10 in standard settings. As the tree is kept outside of R direct reach, context trees built with the C++ back end must be restored after a saveRDS()/readRDS() sequence. This is done automatically by recomputing completely the context tree.

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
## get all contexts of length 2
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 2)
draw(rdts_ctree)

Description

This function builds a context tree for a time series.

Usage

## S3 method for class 'dts'
ctx_tree(
  x,
  min_size = 2L,
  max_depth = 100L,
  keep_position = TRUE,
  backend = getOption("mixvlmc.backend", "R"),
  ...
)

Arguments

Details

The tree represents all the sequences of symbols/states of length smaller than max_depth that appear at least min_size times in the time series and stores the frequencies of the states that follow each context. Optionally, the positions of the contexts in the time series can be stored in the tree.

Value

a context tree (of class that inherits from ctx_tree).

Back ends

Two back ends are available to compute context trees:

• the "R" back end represents the tree in pure R data structures (nested lists) that be easily processed further in pure R (C++ helper functions are used to speed up the construction).

• the "C++" back end represents the tree with C++ classes. This back end is considered experimental. The tree is built with an optimised suffix tree algorithm which speeds up the construction by at least a factor 10 in standard settings. As the tree is kept outside of R direct reach, context trees built with the C++ back end must be restored after a saveRDS()/readRDS() sequence. This is done automatically by recomputing completely the context tree.

Examples

x_dts <- dts(c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0))
## get all contexts of length 2
ctree <- ctx_tree(x_dts, min_size = 1, max_depth = 2)
draw(ctree)

Description

This generic function returns one or more cut off values that are guaranteed to have an effect on the model passed to the function when a simplification procedure is applied (in general a tree pruning operation as provided by prune()).

Usage

cutoff(model, ...)

Arguments

Details

The exact definition of what is a cut off value depends on the model type and is documented in concrete implementation of the function.

Value

a cut off value or a vector of cut off values.

See Also

prune()

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power,
  breaks = c(0, quantile(pc$active_power,
    probs = c(0.25, 0.5, 0.75, 1)
  ))
)
model <- vlmc(rdts)
draw(model)
model_cuts <- cutoff(model)
model_2 <- prune(model, model_cuts[2])
draw(model_2)

Description

This function returns all the cut off values that should induce a pruning of the context tree of a VLMC with covariates.

Usage

## S3 method for class 'covlmc'
cutoff(model, raw = FALSE, tolerance = .Machine$double.eps^0.5, ...)

Arguments

Details

Notice that the list of cut off values returned by the function is not as complete as the one computed for a VLMC without covariates. Indeed, pruning the COVLMC tree creates new pruning opportunities that are not evaluated during the construction of the initial model, while all pruning opportunities are computed during the construction of a VLMC context tree. Nevertheless, the largest value returned by the function is guaranteed to produce the least pruned tree consistent with the reference one.

For large COVLMC, some cut off values can be almost identical, with a difference of the order of the machine epsilon value. The tolerance parameter is used to keep only values that are different enough. This is done in the quantile scale, before transformations implemented when raw is FALSE.

Notice that the loglikelihood scale is not directly useful in COVLMC as the differences in model sizes are not constant through the pruning process. As a consequence, this function does not provide mode parameter, contrarily to cutoff.vlmc().

Setting raw to TRUE removes the small perturbation that are subtracted from the log-likelihood ratio values computed from the COVLMC (in quantile scale).

As automated model selection is provided by tune_covlmc(), the direct use of cutoff should be reserved to advanced exploration of the set of trees that can be obtained from a complex one, e.g. to implement model selection techniques that are not provided by tune_covlmc().

Value

a vector of cut off values, NULL if none can be computed

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
m_nocovariate <- vlmc(rdts)
draw(m_nocovariate)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
draw(m_cov)
cutoff(m_cov)

Description

This function returns the cut off value associated to a specific node in the context tree interpreted as a VLMC. The node is represented by a ctx_node object as returned by find_sequence() or contexts(). For details, see cutoff.vlmc().

Usage

## S3 method for class 'ctx_node'
cutoff(model, scale = c("quantile", "native"), raw = FALSE, ...)

Arguments

Value

a cut off value

See Also

cutoff()

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power,
  breaks = c(0, quantile(pc$active_power,
    probs = c(0.25, 0.5, 0.75, 1)
  ))
)
model <- vlmc(rdts)
model_ctxs <- contexts(model)
cutoff(model_ctxs[[1]])
cutoff(model_ctxs[[2]], scale = "native", raw = TRUE)

Description

This function returns a collection of cut off values that are guaranteed to induce all valid pruned trees of the context tree of a VLMC. Pruning is implemented by the prune() function.

Usage

## S3 method for class 'vlmc'
cutoff(
  model,
  scale = c("quantile", "native"),
  raw = FALSE,
  tolerance = .Machine$double.eps^0.5,
  ...
)

## S3 method for class 'vlmc_cpp'
cutoff(
  model,
  scale = c("quantile", "native"),
  raw = FALSE,
  tolerance = .Machine$double.eps^0.5,
  ...
)

Arguments

Details

By default, the function returns values that can be used directly to induce pruning in the context tree. This is done by computing the log likelihood ratios used by the context algorithm on the reference VLMC and by keeping the relevant ones. From them the function selects intermediate values that are guaranteed to generate via pruning all the VLMC models that could be generated by using larger values of the cutoff parameter that was used to build the reference model (or smaller values of the alpha parameter in "quantile" scale).

Setting the raw parameter to TRUE removes this operation on the values and asks the function to return the relevant log likelihood ratios.

For large VLMC, some log likelihood ratios can be almost identical, with a difference of the order of the machine epsilon value. The tolerance parameter is used to keep only values that are different enough. This is done in the native scale, before transformations implemented when raw is FALSE.

As automated model selection is provided by tune_vlmc(), the direct use of cutoff should be reserved to advanced exploration of the set of trees that can be obtained from a complex one, e.g. to implement model selection techniques that are not provided by tune_vlmc().

Value

a vector of cut off values.

See Also

prune() and tune_vlmc()

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power,
  breaks = c(0, quantile(pc$active_power,
    probs = c(0.25, 0.5, 0.75, 1)
  ))
)
model <- vlmc(rdts)
draw(model)
model_cuts <- cutoff(model)
model_2 <- prune(model, model_cuts[2])
draw(model_2)

Description

This function returns the depth of a context tree, i.e. the length of the longest context represented in the tree.

Usage

depth(ct)

Arguments

Value

the depth of the tree.

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3)
## should be 3
depth(rdts_ctree)

Description

This function 'draws' a context tree as a text.

Usage

draw(ct, format, control = draw_control(), ...)

Arguments

Details

The function uses different text based formats (plain "ascii art" and LaTeX) to represent the context tree. Fine tuning of the representation can be done via the draw_control() function.

In addition to the structure of the context tree, draw() can represent information attached to the nodes (contexts and partial contexts). This is controlled by additional parameters depending on the type of the context tree. In general, parameters given directly to draw() specify what information is represented while details on how this representation is made can be controlled via the control parameter and the associated draw_control() function.

Value

the context tree (invisibly).

Format

The format parameter specifies the format used for the textual output. With the default value "text" the output is produced in "ascii art" using by default only ascii characters (notice that draw_control() can be used to specified non ascii characters, but this is discouraged).

With the latex value, the output is produced in LaTeX, leveraging the forest Latex package (see https://ctan.org/pkg/forest). Each call to draw() produces a full forest LaTeX environment. This can be included as is in a LaTeX document, provided the forest package is loaded in the preamble of the document. The LaTeX output is sanitized to avoid potential problems induced by special characters in the names of the states of the context tree.

Examples

rdts <- sample(c(0, 1), 100, replace = TRUE)
ctree <- ctx_tree(rdts, min_size = 10, max_depth = 2)
draw(ctree)
rdts_c <- sample(c("A", "B", "CD"), 100, replace = TRUE)
ctree_c <- ctx_tree(rdts_c, min_size = 10, max_depth = 2)
draw(ctree_c, control = draw_control(digits = 2))
## LaTeX output
draw(ctree_c, "latex")

Description

This function returns a list used to fine tune the draw() function behaviour.

Usage

draw_control(
  digits = 4,
  charset = NULL,
  orientation = c("vertical", "horizontal"),
  tabular = TRUE,
  tab_orientation = c("vertical", "horizontal"),
  decoration = c("none", "rectangle", "circle", "ellipse"),
  fontsize = "normalsize",
  prob_fontsize = "small"
)

Arguments

Details

Parameters are generally specific to the format used for draw(). If this is the case, the format is given at the end of the parameter description. Some parameters are also specific to some functions inheriting from draw().

Value

a list

Decoration

The LaTeX format ("latex") can "decorate" the nodes of the context tree by drawing borders. We support only basic decorations, but in theory all TikZ possibilities could be used (see the documentation of the forest LaTeX package). Supported decorations:

• "none": default, no decoration;

• "rectangle": adds a rectangular border to all nodes;

• "circle": adds a circular border to all nodes;

• "ellipse": adds an ellipsoidal border to all nodes.

Charset

The "ascii art" format ("text") uses a collection of characters to display a context tree. The default collection is specified by the package option "mixvlmc.charset" and is used when charset=NULL (default value). If charset is set to a character value, this value is used to select the collection in the same way that "mixvlmc.charset" specifies it:

• "ascii": the collection uses only standard ASCII characters and should be compatible with all environments;

• "utf8": the collection uses UTF-8 symbols and needs a compatible display.

Finally, charset can a user supplied list of characters as the one returned by charset_ascii() and charset_utf8().

See Also

draw(), charset_ascii() and charset_utf8().

Examples

draw_control(digits = 2, tabular = FALSE)

Description

This function 'draws' a covlmc as a text.

Usage

## S3 method for class 'covlmc'
draw(
  ct,
  format,
  control = draw_control(),
  model = c("coef", "full"),
  p_value = FALSE,
  with_state = FALSE,
  constant_as_prob = TRUE,
  ...
)

Arguments

Details

The function uses different text based formats (plain "ascii art" and LaTeX) to represent the context tree. Fine tuning of the representation can be done via the draw_control() function.

Contrarily to draw() functions adapted to context trees draw.ctx_tree() and VLMC draw.vlmc(), the present function does not try to produce similar results for the "text" format and the "latex" format as the "text" format is intrinsically more limited in terms of model representations. This is detailed below.

Format

The format parameter specifies the format used for the textual output. With the default value "text" the output is produced in "ascii art" using the charset specified by the global option mixvlmc.charset.

With the latex value, the output is produced in LaTeX, leveraging the forest Latex package (see https://ctan.org/pkg/forest). Each call to draw.covlmc() produces a full forest LaTeX environment. This can be included as is in a LaTeX document, provided the forest package is loaded in the preamble of the document. The LaTeX output is sanitized to avoid potential problems induced by special characters in the names of the states of the context tree.

"text" format

Parameters

When format="text" the parameters are interpreted as follows:

• model: the default model="coef" represents only the coefficients of the logistic models associated to each context. model="full" includes the name of the variables in the representation. Setting model=NULL removes the model representations. Additional parameters can be used to tweak model representations (see below).

• constant_as_prob: specifies whether to represent logistic models that do not use covariates (a.k.a. constant models) using the probability distributions they induce on the state space (default behaviour with constant_as_prob=TRUE) or as normal models (when set to FALSE). This is not taken into account when model is not set to "coef".

• fields of the control list (including the charset):

  • intercept : character(s) used to represent the intercept when model="full"

  • intercept_sep: character(s) used to separate the intercept from the other coefficients in model representation.

  • time_sep: character(s) used to split the coefficients list by blocks associated to time delays in the covariate inclusion into the logistic model. The first block contains the intercept(s), the second block the covariate values a time t-1, the third block at time t-2, etc.

  • level_sep: character(s) used separate levels from model, see below.

  • open_p_value and close_p_value: delimiters used around the p-values when p_value=TRUE

  • open_model and close_model: delimiters around the model when model is not NULL

State representation

When model is not NULL, the coefficients of the logistic models are presented, organized in rows associated to states. One state is used as the reference state and the logistic model aims at predicting the ratio of probability between another state and the reference one (in log scale). When with_state is TRUE, the display includes for each row of coefficients the target state. This is useful when using e.g. VGAM::vglm() as unused levels of the target variable will be automatically dropped from the model, leading to a reduce number of rows. The reference state is either shown on the first row if model is "full" or after the state on each row if model is "coef". States are separated from the model representation by the character(s) specified in level_sep in the control list.

"latex" format

Parameters

When format="latex" the parameters are interpreted as follows:

• model: the models are always represented completely in the LaTeX export unless model is set to NULL.

• constant_as_prob: in the LaTeX export, constant logistic models are always represented by the corresponding probability distribution on the state space, regardless of the value of constant_as_prob.

• fields of the control list:

  • orientation: specifies the orientation of the tree, either the default "vertical" (expanding from top to bottom) or "horizontal" (expanding from right to left);

  • tab_orientation: specifies the orientation of the tables used to represent model coefficients in the tree, either the default "vertical" (covariates are listed on one column) or "horizontal" (covariates are listed on one row);

  • fontsize and prob_fontsize handle the size of the fonts used for the states and for the models, see draw_control() for details;

  • decoration can be used to add borders around states, see draw_control() for details;

State representation

When model is not NULL, the coefficients of the logistic models are presented, organized in rows or in columns (depending tab_orientation) on associated to states. One state is used as the reference state and the logistic model aims at predicting the ratio of probability between another state and the reference one (in log scale). When with_state is TRUE, the display includes for each row/column of coefficients the target state. The reference state is shown on the first row/column.

Variable representation

When the representation includes the names of the variables used by the logistic models, they are the one generated by the underlying logistic model, e.g. stats::glm(). Numerical variable names are used as is, while factors have levels appended. The intercept is denoted by the intercept member of the control list whenformat="text" (as part of the charset). It is always represented by (I) when format="latex".

When format="text", the time delays are represented by an underscore followed by the time delay. For instance if the model uses the numerical covariate y with two delays, it will appear with two variables y_1 and y_2.

When format="latex", the representation uses a temporal subscript of the form t-1, t-2, etc.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power,
  breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1)))
)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
draw(m_cov, control = draw_control(digits = 3))
draw(m_cov, model = NULL)
draw(m_cov, p_value = TRUE)
draw(m_cov, p_value = FALSE, control = draw_control(digits = 2))
draw(m_cov, model = "full", control = draw_control(digits = 3))
draw(m_cov, format = "latex", control = draw_control(orientation = "h"))

Description

This function 'draws' a context tree as a text.

Usage

## S3 method for class 'ctx_tree_cpp'
draw(ct, format, control = draw_control(), frequency = NULL, ...)

## S3 method for class 'ctx_tree'
draw(ct, format, control = draw_control(), frequency = NULL, ...)

Arguments

Details

The function uses different text based formats (plain "ascii art" and LaTeX) to represent the context tree. Fine tuning of the representation can be done via the draw_control() function.

In addition to the structure of the context tree, draw() can represent information attached to the nodes (contexts and partial contexts). This is controlled by additional parameters depending on the type of the context tree. In general, parameters given directly to draw() specify what information is represented while details on how this representation is made can be controlled via the control parameter and the associated draw_control() function.

Value

the context tree (invisibly).

Format

The format parameter specifies the format used for the textual output. With the default value "text" the output is produced in "ascii art" using by default only ascii characters (notice that draw_control() can be used to specified non ascii characters, but this is discouraged).

With the latex value, the output is produced in LaTeX, leveraging the forest Latex package (see https://ctan.org/pkg/forest). Each call to draw() produces a full forest LaTeX environment. This can be included as is in a LaTeX document, provided the forest package is loaded in the preamble of the document. The LaTeX output is sanitized to avoid potential problems induced by special characters in the names of the states of the context tree.

Examples

rdts_c <- sample(c("A", "B", "CD"), 100, replace = TRUE)
ctree_c <- ctx_tree(rdts_c, min_size = 10, max_depth = 2)
draw(ctree_c, frequency = "total")
draw(ctree_c, frequency = "detailed")
## LaTeX output
draw(ctree_c, "latex", frequency = "detailed")
rdts_c <- sample(c("A$", "_{B", "{C}_{D}"), 100, replace = TRUE)
ctree_c <- ctx_tree(rdts_c, min_size = 10, max_depth = 2)
## the LaTeX output is sanitized
draw(ctree_c, "latex", frequency = "detailed")

Description

This function 'draws' a context tree as a text.

Usage

## S3 method for class 'vlmc'
draw(ct, format, control = draw_control(), prob = TRUE, ...)

## S3 method for class 'vlmc_cpp'
draw(ct, format, control = draw_control(), prob = TRUE, ...)

Arguments

Details

The function uses different text based formats (plain "ascii art" and LaTeX) to represent the context tree. Fine tuning of the representation can be done via the draw_control() function.

In addition to the structure of the context tree, draw() can represent information attached to the nodes (contexts and partial contexts). This is controlled by additional parameters depending on the type of the context tree. In general, parameters given directly to draw() specify what information is represented while details on how this representation is made can be controlled via the control parameter and the associated draw_control() function.

Value

the context tree (invisibly).

Format

The format parameter specifies the format used for the textual output. With the default value "text" the output is produced in "ascii art" using by default only ascii characters (notice that draw_control() can be used to specified non ascii characters, but this is discouraged).

With the latex value, the output is produced in LaTeX, leveraging the forest Latex package (see https://ctan.org/pkg/forest). Each call to draw() produces a full forest LaTeX environment. This can be included as is in a LaTeX document, provided the forest package is loaded in the preamble of the document. The LaTeX output is sanitized to avoid potential problems induced by special characters in the names of the states of the context tree.

Examples

rdts <- sample(c("A", "B", "C"), 500, replace = TRUE)
model <- vlmc(rdts, alpha = 0.05)
draw(model)
draw(model, prob = FALSE)
draw(model, prob = NULL)

Description

This function creates a representation of a discrete time series that can be further processed by model estimation functions.

Usage

dts(x, vals = NULL)

Arguments

Details

The discrete time series x can be a vector of numeric, character, factor or logical type. If the state space of the series is not specified, that is when vals is NULL, it is computed in a way that depends on the type of x:

• for a factor, vals is set to the levels() of x;

• for a logical vector, vals is set to c(FALSE, TRUE);

• for other types, vals is set to all the unique values taken by the time series (as returned by sort(unique(x))).

If vals is specified, the function makes sure that x contains only the specified values.

Value

a discrete time series (of class that inherits from dts).

Examples

x_dts <- dts(sample(c("A", "B"), 20, replace = TRUE))
x_dts

Description

This function returns a copy of the discrete time series used to build the dts object (see dts()).

Usage

dts_data(x)

Arguments

Value

a vector representing the time seris

Examples

raw_dts <- sample(c("A", "B", "C"), 50, replace = TRUE)
odts <- dts(raw_dts)
back_to_raw <- dts_data(odts)
## should be TRUE
identical(raw_dts, back_to_raw)

Description

This function checks whether the sequence ctx is represented in the context tree ct. If this is the case, it returns a description of matching node, an object of class ctx_node. If the sequence is not represented in the tree, the function return NULL.

Usage

find_sequence(ct, ctx, reverse = FALSE, ...)

## S3 method for class 'ctx_tree'
find_sequence(ct, ctx, reverse = FALSE, ...)

## S3 method for class 'ctx_tree_cpp'
find_sequence(ct, ctx, reverse = FALSE, ...)

Arguments

Details

The function looks for sequences in general. The is_context() function can be used on the resulting object to test if the sequence is in addition a proper context.

Value

an object of class ctx_node if the sequence ctx is represented in the context tree, NULL when this is not the case.

State order in a sequence

sequence 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. In the present function, reverse refers both to the order used for the ctx parameter and for the default order used by the resulting ctx_node object.

Examples

rdts <- c("A", "B", "C", "A", "A", "B", "B", "C", "C", "A")
rdts_tree <- ctx_tree(rdts, max_depth = 3)
find_sequence(rdts_tree, "A")
## returns NULL as "A" "C" does not appear in rdts
find_sequence(rdts_tree, c("A", "C"))

Description

This function checks whether the sequence ctx is represented in the context tree of the COVLMC model ct. If this is the case, it returns a description of matching node, an object of class ctx_node_covlmc. If the sequence is not represented in the tree, the function return NULL.

Usage

## S3 method for class 'covlmc'
find_sequence(ct, ctx, reverse = FALSE, ...)

Arguments

Details

The function looks for sequences in general. The is_context() function can be used on the resulting object to test if the sequence is in addition a proper context.

Value

an object of class ctx_node_covlmc if the sequence ctx is represented in the context tree, NULL when this is not the case

State order in a sequence

sequence 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. In the present function, reverse refers both to the order used for the ctx parameter and for the default order used by the resulting ctx_node object.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 10)

## not in the tree
vals <- states(m_cov)
find_sequence(m_cov, c(vals[2], vals[2]))
## in the tree but not a context
node <- find_sequence(m_cov, c(vals[1]))
node
is_context(node)
## in the tree and a context
node <- find_sequence(m_cov, c(vals[1], vals[1]))
node
is_context(node)
model(node)

Description

A data set containing Earthquake that have occured during the period of 1900-2022 with GPS coordinates and magnitudes.

Usage

globalearthquake

Format

A data frame with 98785 rows and 12 variables:

date_time

Date and time in POSIXct format

latitude

latitude of the earthquake, from -90° to 90°

longitude

longitude of the earthquake, from -180° to 180°

mag

the magnitude of the earthquake, indicating its strenth

Date

date when the seisme occured

nbweeks

number of weeks since 1900/01/01

year

year

month

month of the year

month_day

day of the month

week

week number

week_day

day of the week from 1 = Sunday to 7 = Saturday

year_day

day of the year from 1 to 366

Details

This is a compiled version of the full data set available on U.S. Geological Survey Earthquake Events (USGS) which is in the public domain.

The data set contains only the earthquake between 1900 and 2022 with a magnitude higher than 5.

Source

Earthquake Catalog, U.S. Geological Survey, Department of the Interior. https://www.usgs.gov/programs/earthquake-hazards

Description

This function returns TRUE if the node is a proper context, FALSE in the other case.

Usage

is_context(node)

Arguments

Value

TRUE if the node node is a proper context, FALSE when this is not the case

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3)
draw(rdts_ctree)
## 0, 0 is a context but 1, 0 is not
is_context(find_sequence(rdts_ctree, c(0, 0)))
is_context(find_sequence(rdts_ctree, c(1, 0)))

Description

This function returns TRUE for VLMC models with covariates and FALSE for other objects.

Usage

is_covlmc(x)

Arguments

Value

TRUE for VLMC models with covariates.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power, breaks = c(0, quantile(pc$active_power, probs = c(0.5, 1))))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
# should be true
is_ctx_tree(m_cov)
# should be true
is_covlmc(m_cov)
# should be false
is_vlmc(m_cov)

Description

This function returns TRUE for context trees and FALSE for other objects.

Usage

is_ctx_tree(x)

Arguments

Value

TRUE for context trees.

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 2)
is_ctx_tree(rdts_ctree)
is_ctx_tree(rdts)

Description

This function returns TRUE for discrete time series and FALSE for other objects.

Usage

is_dts(x)

Arguments

Value

TRUE for discrete time series.

Examples

pre_dts <- sample(c("A", "B"), 20, replace = TRUE)
x_dts <- dts(pre_dts)
is_dts(x_dts)
is_dts(pre_dts)

Description

The function returns TRUE if the context represented by this node is merged with at least another one and FALSE if this is not the case.

Usage

is_merged(node)

Arguments

Details

When a COVLMC is built on a time series with at least three distinct states, some contexts can be merged: they use the same logistic model, leading to a more parsimonious model. Those contexts are reported individually by functions such as contexts.covlmc(). The present function can be used to detect such merging, while merged_with() can be used to recover the other contexts.

Value

TRUE or FALSE, depending on the nature of the context

See Also

merged_with()

Examples

pc <- powerconsumption[powerconsumption$week == 15, ]
rdts <- cut(pc$active_power, breaks = c(0, 1, 2, 3, 8))
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5, alpha = 0.1)
ctxs <- contexts(m_cov)
## no merging
sapply(ctxs, is_merged)

Description

This function returns TRUE if the node is using a reverse temporal ordering and FALSE in the other case.

Usage

is_reversed(node)

Arguments

Value

TRUE if the node node use a reverse temporal ordering, FALSE when this is not the case

See Also

rev.ctx_node()

Examples

rdts <- c(0, 1, 1, 1, 0, 0, 1, 0, 1, 0)
rdts_ctree <- ctx_tree(rdts, min_size = 1, max_depth = 3)
is_reversed(find_sequence(rdts_ctree, c(0, 0)))
is_reversed(find_sequence(rdts_ctree, c(1, 0), reverse = TRUE))

Description

This function returns TRUE for VLMC models and FALSE for other objects.

Usage

is_vlmc(x)

Arguments

Value

TRUE for VLMC models.

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power,
  breaks = c(0, quantile(pc$active_power,
    probs = c(0.25, 0.5, 0.75, 1)
  ))
)
model <- vlmc(rdts)
# should be true
is_ctx_tree(model)
# should be true
is_vlmc(model)
# should be false
is_covlmc(model)

Description

This function evaluates the log-likelihood of a VLMC with covariates fitted on a discrete time series.

Usage

## S3 method for class 'covlmc'
logLik(object, initial = c("truncated", "specific", "extended"), ...)

Arguments

Value

an object of class logLik. This is a number, the log-likelihood of the (CO)VLMC with the following attributes:

• df: the number of parameters used by the VLMC for this likelihood calculation

• nobs: the number of observations included in this likelihood calculation

• initial: the value of the initial parameter used to compute this likelihood

See Also

loglikelihood()

Examples

## Likelihood for a fitted VLMC with covariates.
pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
ll <- logLik(m_cov)
attributes(ll)

Description

This function evaluates the log-likelihood of a VLMC fitted on a discrete time series.

Usage

## S3 method for class 'vlmc'
logLik(object, initial = c("truncated", "specific", "extended"), ...)

## S3 method for class 'vlmc_cpp'
logLik(object, initial = c("truncated", "specific", "extended"), ...)

Arguments

Value

an object of class logLik. This is a number, the log-likelihood of the (CO)VLMC with the following attributes:

• df: the number of parameters used by the VLMC for this likelihood calculation

• nobs: the number of observations included in this likelihood calculation

• initial: the value of the initial parameter used to compute this likelihood

See Also

loglikelihood()

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
m_nocovariate <- vlmc(rdts)
ll <- logLik(m_nocovariate)
ll
attributes(ll)

Description

This function evaluates the log-likelihood of a VLMC fitted on a discrete time series. When the optional argument newdata is provided, the function evaluates instead the log-likelihood for this (new) discrete time series.

Usage

loglikelihood(
  vlmc,
  newdata,
  initial = c("truncated", "specific", "extended"),
  ignore,
  ...
)

## S3 method for class 'vlmc'
loglikelihood(
  vlmc,
  newdata,
  initial = c("truncated", "specific", "extended"),
  ignore,
  ...
)

## S3 method for class 'vlmc_cpp'
loglikelihood(
  vlmc,
  newdata,
  initial = c("truncated", "specific", "extended"),
  ignore,
  ...
)

Arguments

Details

The definition of the likelihood function depends on the value of the initial parameters, see the section below as well as the dedicated vignette: vignette("likelihood", package = "mixvlmc").

For VLMC objects, the method loglikelihood.vlmc will be used. For VLMC with covariables, loglikelihood.covlmc will instead be called. For more informations on loglikelihood methods, use methods(loglikelihood) and their associated documentation.

Value

an object of class logLikMixVLMC and logLik. This is a number, the log-likelihood of the (CO)VLMC with the following attributes:

• df: the number of parameters used by the VLMC for this likelihood calculation

• nobs: the number of observations included in this likelihood calculation

• initial: the value of the initial parameter used to compute this likelihood

likelihood calculation

In a (CO)VLMC of depth()=k, we need k past values in order to compute the context of a given observation. As a consequence, in a time series x, the contexts of x[1] to x[k] are unknown. Depending on the value of initial different likelihood functions are used to tackle this difficulty:

• initial=="truncated": the likelihood is computed using only x[(k+1):length(x)]

• initial=="specific": the likelihood is computed on the full time series using a specific context for the initial values, x[1] to x[k]. Each of the specific context is unique, leading to a perfect likelihood of 1 (0 in log scale). Thus the numerical value of the likelihood is identical as the one obtained with initial=="truncated" but it is computed on length(x) with a model with more parameters than in this previous case.

• initial=="extended" (default): the likelihood is computed on the full time series using an extended context matching for the initial values, x[1] to x[k]. This can be seen as a compromised between the two other possibilities: the relaxed context matching needs in general to turn internal nodes of the context tree into actual context, increasing the number of parameters, but not as much as with "specific". However, the likelihood of say x[1] with an empty context is generally not 1 and thus the full likelihood is smaller than the one computed with "specific".

In all cases, the ignore first values of the time series are not included in the computed likelihood, but still used to compute contexts. If ignore is not specified, it is set to the minimal possible value, that is k for the truncated likelihood and 0 for the other ones. If it is specified, it must be larger or equal to k for truncated.

See the dedicated vignette for a more mathematically oriented discussion: vignette("likelihood", package = "mixvlmc").

See Also

stats::logLik()

Examples

## Likelihood for a fitted VLMC.
pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
m_nocovariate <- vlmc(rdts)
ll <- loglikelihood(m_nocovariate)
ll
attr(ll, "nobs")
attr(ll, "df")

## Likelihood for a new time series with previously fitted VLMC.
pc_new <- powerconsumption[powerconsumption$week == 11, ]
rdts_new <- cut(pc_new$active_power, breaks = breaks, labels = labels)
ll_new <- loglikelihood(m_nocovariate, newdata = rdts_new)
ll_new
attributes(ll_new)
ll_new_specific <- loglikelihood(m_nocovariate, initial = "specific", newdata = rdts_new)
ll_new_specific
attributes(ll_new_specific)
ll_new_extended <- loglikelihood(m_nocovariate, initial = "extended", newdata = rdts_new)
ll_new_extended
attributes(ll_new_extended)

Description

This function evaluates the log-likelihood of a VLMC with covariates fitted on a discrete time series. When the optional arguments newdata is provided, the function evaluates instead the log-likelihood for this (new) discrete time series on the new covariates which must be provided through the newcov parameter.

Usage

## S3 method for class 'covlmc'
loglikelihood(
  vlmc,
  newdata,
  initial = c("truncated", "specific", "extended"),
  ignore,
  newcov,
  ...
)

Arguments

Details

The definition of the likelihood function depends on the value of the initial parameters, see the section below as well as the dedicated vignette: vignette("likelihood", package = "mixvlmc").

Value

an object of class logLikMixVLMC and logLik. This is a number, the log-likelihood of the (CO)VLMC with the following attributes:

• df: the number of parameters used by the VLMC for this likelihood calculation

• nobs: the number of observations included in this likelihood calculation

• initial: the value of the initial parameter used to compute this likelihood

likelihood calculation

In a (CO)VLMC of depth()=k, we need k past values in order to compute the context of a given observation. As a consequence, in a time series x, the contexts of x[1] to x[k] are unknown. Depending on the value of initial different likelihood functions are used to tackle this difficulty:

• initial=="truncated": the likelihood is computed using only x[(k+1):length(x)]

• initial=="specific": the likelihood is computed on the full time series using a specific context for the initial values, x[1] to x[k]. Each of the specific context is unique, leading to a perfect likelihood of 1 (0 in log scale). Thus the numerical value of the likelihood is identical as the one obtained with initial=="truncated" but it is computed on length(x) with a model with more parameters than in this previous case.

• initial=="extended" (default): the likelihood is computed on the full time series using an extended context matching for the initial values, x[1] to x[k]. This can be seen as a compromised between the two other possibilities: the relaxed context matching needs in general to turn internal nodes of the context tree into actual context, increasing the number of parameters, but not as much as with "specific". However, the likelihood of say x[1] with an empty context is generally not 1 and thus the full likelihood is smaller than the one computed with "specific".

In all cases, the ignore first values of the time series are not included in the computed likelihood, but still used to compute contexts. If ignore is not specified, it is set to the minimal possible value, that is k for the truncated likelihood and 0 for the other ones. If it is specified, it must be larger or equal to k for truncated.

See the dedicated vignette for a more mathematically oriented discussion: vignette("likelihood", package = "mixvlmc").

See Also

stats::logLik()

Examples

## Likelihood for a fitted VLMC with covariates.
pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
ll <- loglikelihood(m_cov)
ll
attr(ll, "nobs")

## Likelihood for new time series and covariates with previously
## fitted VLMC with covariates
pc_new <- powerconsumption[powerconsumption$week == 11, ]
rdts_new <- cut(pc_new$active_power, breaks = breaks, labels = labels)
rdts_cov_new <- data.frame(day_night = (pc_new$hour >= 7 & pc_new$hour <= 17))
ll_new <- loglikelihood(m_cov, newdata = rdts_new, newcov = rdts_cov_new)
ll_new
attributes(ll_new)

Description

The function returns NULL when the context represented by the node parameter is not merged with another context (see is_merged()). In the other case, it returns a list of contexts with which this one is merged.

Usage

merged_with(node)

Arguments

Details

If the context is merged, the function returns a list with one value for each element in the state space (see states()). The value is NULL if the corresponding context is not merged with the node context, while it is a ctx_node_covlmc object in the other case. A context merged with node differs from the context represented by node only in its last value (in temporal order) which is used as its name in the list. For instance, if the context ABC is merged only with CBC (when represented in temporal ordering), then the resulting list is of the form list("A" = NULL, "B" = NULL, "C"= ctx_node_covlmc(CBX)).

Value

NULL or a list of contexts merged with node represented by ctx_node_covlmc objects

See Also

is_merged()

Examples

pc_week_15_16 <- powerconsumption[powerconsumption$week %in% c(15, 16), ]
elec <- pc_week_15_16$active_power
elec_rdts <- cut(elec, breaks = c(0, 0.4, 2, 8), labels = c("low", "typical", "high"))
elec_cov <- data.frame(day = (pc_week_15_16$hour >= 7 & pc_week_15_16$hour <= 18))
elec_tune <- tune_covlmc(elec_rdts, elec_cov, min_size = 5)
elec_model <- prune(as_covlmc(elec_tune), alpha = 3.961e-10)
ctxs <- contexts(elec_model)
for (ctx in ctxs) {
  if (is_merged(ctx)) {
    print(ctx)
    cat("\nis merged with\n\n")
    print(merged_with(ctx))
  }
}

Description

This function computes and returns predictive quality metrics for context based models such as VLMC and VLMC with covariates.

Usage

metrics(model, ...)

Arguments

Details

A context based model computes transition probabilities for its contexts. Using a maximum transition probability decision rule, this can be used to predict the new state that is the more likely to follow the current one, given the context (see predict.vlmc()). The quality of these predictions is evaluated using standard metrics including:

• accuracy

• the full confusion matrix

• the area under the roc curve (AUC), considering the context based model as a (conditional) probability estimator. We use Hand and Till (2001) multiclass AUC in case of a state space with more than 2 states

Value

The returned value is guaranteed to have at least three components

• accuracy: the accuracy of the predictions

• conf_mat: the confusion matrix of the predictions, with predicted values in rows and true values in columns

• auc: the AUC of the predictive model

References

David J. Hand and Robert J. Till (2001). "A Simple Generalisation of the Area Under the ROC Curve for Multiple Class Classification Problems." Machine Learning 45(2), p. 171–186. DOI: doi:10.1023/A:1010920819831.

See Also

metrics.vlmc(), metrics.ctx_node(), contexts.vlmc(), predict.vlmc().

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
model <- vlmc(rdts)
metrics(model)

Description

This function computes and returns predictive quality metrics for context based models such as VLMC and VLMC with covariates.

Usage

## S3 method for class 'covlmc'
metrics(model, ...)

## S3 method for class 'metrics.covlmc'
print(x, ...)

Arguments

Details

A context based model computes transition probabilities for its contexts. Using a maximum transition probability decision rule, this can be used to predict the new state that is the more likely to follow the current one, given the context (see predict.vlmc()). The quality of these predictions is evaluated using standard metrics including:

• accuracy

• the full confusion matrix

• the area under the roc curve (AUC), considering the context based model as a (conditional) probability estimator. We use Hand and Till (2001) multiclass AUC in case of a state space with more than 2 states

Value

An object of class metrics.covlmc with the following components:

• accuracy: the accuracy of the predictions

• conf_mat: the confusion matrix of the predictions, with predicted values in rows and true values in columns

• auc: the AUC of the predictive model

The object has a print method that recalls basic information about the model together with the values of the components above.

Methods (by generic)

• print(metrics.covlmc): Prints the predictive metrics of the VLMC model with covariates.

Extended contexts

As explained in details in loglikelihood.covlmc() documentation and in the dedicated vignette("likelihood", package = "mixvlmc"), the first initial values of a time series do not in general have a proper context for a COVLMC with a non zero order. In order to predict something meaningful for those values, we rely on the notion of extended context defined in the documents mentioned above. This follows the same logic as using loglikelihood.covlmc() with the parameter initial="extended". All covlmc functions that need to manipulate initial values with no proper context use the same approach.

References

David J. Hand and Robert J. Till (2001). "A Simple Generalisation of the Area Under the ROC Curve for Multiple Class Classification Problems." Machine Learning 45(2), p. 171–186. DOI: doi:10.1023/A:1010920819831.

See Also

metrics.vlmc(), metrics.ctx_node(), contexts.vlmc(), predict.vlmc().

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
metrics(m_cov)

Description

This function computes and returns predictive quality metrics for a node (ctx_node) extracted from a context tree.

Usage

## S3 method for class 'ctx_node'
metrics(model, ...)

Arguments

Details

Compared to metrics.vlmc(), this function focuses on a single context and assesses the quality of its predictions, disregarding observations that have other contexts. Apart from this limited scope, the function operates as metrics.vlmc().

Value

The returned value is guaranteed to have at least three components

• accuracy: the accuracy of the predictions

• conf_mat: the confusion matrix of the predictions, with predicted values in rows and true values in columns

• auc: the AUC of the predictive model

References

David J. Hand and Robert J. Till (2001). "A Simple Generalisation of the Area Under the ROC Curve for Multiple Class Classification Problems." Machine Learning 45(2), p. 171–186. DOI: doi:10.1023/A:1010920819831.

See Also

metrics.vlmc(), metrics.ctx_node(), contexts.vlmc(), predict.vlmc().

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
rdts <- cut(pc$active_power,
  breaks = c(0, quantile(pc$active_power,
    probs = c(0.25, 0.5, 0.75, 1)
  ))
)
model <- vlmc(rdts)
model_ctxs <- contexts(model)
metrics(model_ctxs[[4]])

Description

This function computes and returns predictive quality metrics for a node (ctx_node_covlmc) extracted from a covlmc

Usage

## S3 method for class 'ctx_node_covlmc'
metrics(model, ...)

Arguments

Details

Compared to metrics.covlmc(), this function focuses on a single context and assesses the quality of its predictions, disregarding observations that have other contexts. Apart from this limited scope, the function operates as metrics.covlmc().

Value

an object of class metrics.covlmc with the following components:

• accuracy: the accuracy of the predictions

• conf_mat: the confusion matrix of the predictions, with predicted values in rows and true values in columns

• auc: the AUC of the predictive model

References

David J. Hand and Robert J. Till (2001). "A Simple Generalisation of the Area Under the ROC Curve for Multiple Class Classification Problems." Machine Learning 45(2), p. 171–186. DOI: doi:10.1023/A:1010920819831.

See Also

metrics.vlmc(), metrics.ctx_node(), contexts.vlmc(), predict.vlmc().

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
rdts_cov <- data.frame(day_night = (pc$hour >= 7 & pc$hour <= 17))
m_cov <- covlmc(rdts, rdts_cov, min_size = 5)
m_ctxs <- contexts(m_cov)
## get the predictive metrics for each context
lapply(m_ctxs, metrics)

Description

This function computes and returns predictive quality metrics for context based models such as VLMC and VLMC with covariates.

Usage

## S3 method for class 'vlmc'
metrics(model, ...)

## S3 method for class 'metrics.vlmc'
print(x, ...)

Arguments

Details

A context based model computes transition probabilities for its contexts. Using a maximum transition probability decision rule, this can be used to predict the new state that is the more likely to follow the current one, given the context (see predict.vlmc()). The quality of these predictions is evaluated using standard metrics including:

• accuracy

• the full confusion matrix

• the area under the roc curve (AUC), considering the context based model as a (conditional) probability estimator. We use Hand and Till (2001) multiclass AUC in case of a state space with more than 2 states

Value

An object of class metrics.vlmc with the following components:

• accuracy: the accuracy of the predictions

• conf_mat: the confusion matrix of the predictions, with predicted values in rows and true values in columns

• auc: the AUC of the predictive model

The object has a print method that recalls basic information about the model together with the values of the components above.

Methods (by generic)

• print(metrics.vlmc): Prints the predictive metrics of the VLMC model.

Extended contexts

As explained in details in loglikelihood.vlmc() documentation and in the dedicated vignette("likelihood", package = "mixvlmc"), the first initial values of a time series do not in general have a proper context for a VLMC with a non zero order. In order to predict something meaningful for those values, we rely on the notion of extended context defined in the documents mentioned above. This follows the same logic as using loglikelihood.vlmc() with the parameter initial="extended". All vlmc functions that need to manipulate initial values with no proper context use the same approach.

References

David J. Hand and Robert J. Till (2001). "A Simple Generalisation of the Area Under the ROC Curve for Multiple Class Classification Problems." Machine Learning 45(2), p. 171–186. DOI: doi:10.1023/A:1010920819831.

See Also

metrics.vlmc(), metrics.ctx_node(), contexts.vlmc(), predict.vlmc().

Examples

pc <- powerconsumption[powerconsumption$week == 5, ]
breaks <- c(
  0,
  median(powerconsumption$active_power, na.rm = TRUE),
  max(powerconsumption$active_power, na.rm = TRUE)
)
labels <- c(0, 1)
rdts <- cut(pc$active_power, breaks = breaks, labels = labels)
model <- vlmc(rdts)
metrics(model)