buildWeatherGenerator: Build a Discrete Bayesian Network Weather Generator.
In MNLR/BNWeatherGen: Weather Generators with Bayesian Networks

buildWeatherGenerator

R Documentation

Build a Discrete Bayesian Network Weather Generator.

Description

Builds a discrete weather generator Bayesian network model, using bnlearn. Data should be discretized prior to calling the function by the user. The Bayesian network will approximate the Joint Probability Distribution of the dataset y considering the temporal order specified in epochs.

Usage

buildWeatherGenerator(
  y,
  x = NULL,
  structure.learning.algorithm = "tabu",
  structure.learning.args.list = list(),
  param.learning.method = "bayes",
  epochs = 2,
  force.DD = NULL,
  forbid.GG = FALSE,
  forbid.DD = FALSE,
  forbid.DtoG = FALSE,
  force.closest.GD = NULL,
  closest.GD.direction = NULL,
  forbid.GD = FALSE,
  structure.learning.steps = 1,
  fix.intermediate = TRUE,
  structure.learning.algorithm2 = NULL,
  structure.learning.args.list2 = list(),
  structure.learning.algorithm3 = NULL,
  structure.learning.args.list3 = list(),
  keep.dynamic.distance = TRUE,
  remove.past.G = TRUE,
  forbid.backwards = FALSE,
  forbid.past.dynamic.GD = TRUE,
  forbid.dynamic.GG = FALSE,
  forbid.past.DD = FALSE,
  return.intermediate = FALSE,
  compile.junction = FALSE,
  parallelize = FALSE,
  n.cores = NULL,
  cluster.type = "FORK"
)

Arguments

`y`	Stations dataset, as output by `loadeR::loadStationData()` (see Details)
`x`	By default `NULL`, can be used to provide a predictor dataset, as output by `loadeR::loadGridData()`.
`structure.learning.algorithm`	Algorithm used to perform structure learning, with name as text. Supports all the score-based, constraint-based and hybrid bayesian network structure learning algorithms from `bnlearn`. Refer to `Details` for a list of supported algorithms.
`structure.learning.args.list`	List of arguments passed to structure.learning.algorithm, in particular distance argument if local learning is used. Note that other arguments, e.g. `whitelist`, are an option (check the naming convention, see `Details`). Refer to `bnlearn` for the specific options.
`param.learning.method`	Either "bayes", for bayesian estimation; or "mle", for Maximum Likelihood Estimation.
`epochs`	Number of epochs to consider for Dynamic Bayesian Networks.
`force.DD`	If set to "-", the final DAG will be force to have a link between each station and its past. If set to "->" the arc will be forced from past to present, and from present to past if set to "<-".
`forbid.GG`	If set to TRUE, arcs between grid or G nodes will be forbidden.
`forbid.DD`	If set to TRUE, arcs between local, i.e. station or D nodes, will be forbidden.
`forbid.DtoG`	If set to TRUE, arcs from D nodes to G nodes will be forbidden.
`force.closest.GD`	Expects a positive integer or `NULL`. If not `NULL`, each D node will be linked, see `closest.GD.direction`, with the n closest G node(s), where n is `force.closest.GD`.
`closest.GD.direction`	Either `NULL`, which lets the structure learning algorithm decide the direction, "up", which will place the arc(s) in the form `D -> G`, or "down", which will place the arc(s) in the form `G -> D`.
`forbid.GD`	If set to TRUE, arcs between G and D nodes will be forbidden. See `Details`.
`structure.learning.steps`	It is used to perform structure learning in up to three steps. Note that `past` refers to the past epochs when `dynamic = TRUE`. Refer to `Details`. `1` or `NULL` (Default) 1 step `2` or `c("local", "global")` If `dynamic = FALSE` learn first a DAG for D nodes, then inject G nodes. If `dynamic = TRUE` it equals c("local-global", "past") `3` Equals c("local", "global", "past") `c("local-global", "past")` or `c("global-local", "past")`. Learn first DAG for D and G nodes, then inject past nodes. `c("local", "global-past")` or `c("local", "past-global")`. Learn first DAG for D nodes, then inject past and G nodes. `c("local-past", "global")` or `c("past-local", "global")`. Learn first DAG for D and past nodes, then inject G nodes. `c("local", "global", "past")` Learn first DAG for D nodes, then inject G nodes, then inject past nodes. `c("local", "past", "global")` Learn first DAG for D nodes, then inject past nodes, then inject G nodes. Note that only first two options are valid when `dynamic = FALSE`
`fix.intermediate`	Set to TRUE to forbid the creation of new arcs in the next steps for already built DAGs. See `Details`. `structure.learning.algorithm2` and `structure.learning.args.list2`. See `Details`.
`structure.learning.algorithm2`	Same as structure.learning.algorithm for the second step if `structure.learning.steps` is employed. Ignored otherwise.
`structure.learning.args.list2`	Same as structure.learning.args.list for the second step if `structure.learning.steps` is employed. Ignored otherwise.
`structure.learning.algorithm3`	Same as structure.learning.algorithm for the third step if `structure.learning.steps` with 3 steps is employed. Ignored otherwise.
`structure.learning.args.list3`	Same as structure.learning.args.list for the third step if `structure.learning.steps` with 3 steps is employed. Ignored otherwise. See `Details`.
`keep.dynamic.distance`	When `dynamic = TRUE` and local learning is employed, if set to TRUE it will use its corresponding distance (See `Details`) between nodes from diferent epochs.
`remove.past.G`	When `dynamic = TRUE` Set to TRUE to remove the past G nodes.
`forbid.backwards`	When `dynamic = TRUE`, set to TRUE to forbid arcs going back in time.
`forbid.past.dynamic.GD`	When `dynamic = TRUE`, set to TRUE to forbid arcs in the form G->D or D->G between different epochs.
`forbid.dynamic.GG`	When `dynamic = TRUE` and `remove.past.G = FALSE`, set to TRUE to forbid arcs in the form G-G in the past epochs.
`forbid.past.DD`	When `dynamic = TRUE`, set to TRUE to forbid arcs in the form D-D in the past epochs.
`return.intermediate`	Add the intermediate DAGs to the output, as $intermediateDBN1 and $intermediateDBN2 (if any) if `structure.learning.steps` is employed.
`compile.junction`	Compile the junction tree from BN.fit to compute probabilities. Can be set to FALSE. Compiling the junction tree is necessary for using exact inference at the simulating stage.
`parallelize`	Set to `TRUE` for parallelization. Refer to the `parallel` and see `Details`.
`n.cores`	When `parallelize = TRUE`, number of threads to be used, will use detectCores()-1 if not set.
`cluster.type`	Either "PSOCK" or "FORK". Use the former under Windows systems, refer to `parallel` package.

Details

buildWeatherGenerator() can be used with just a stations dataset. A Grid dataset may be specified by either using parameter x or using a "pp.forBN" class object (as output from preparePredictorsBN()) for parameter y. If none is specified the Bayesian Network may be used as a naive weather generator.

Structure Learning Algorithms Use structure.learning.algorithm to specify the algorithm for the structure (DAG) learning process. Currently it DOES NOT support local discovery algorithms, expect malfuncion if used. List of supported algorithms: "hc", "tabu" (score-based), "gs", "iamb", "fast.iamb", "inter.iamb" (constraint-based), "mmhc", "rsmax2" (hybrid). Check their corresponding parameters in bnlearn, arguments may be passed to the algorithm through the parameter structure.learning.args.list. Do not forget to set the distance argument in structure.learning.args.list for local learning.

Two or Three Step Learning

structure.learning.steps allows to build separate DAGs for each set of nodes. Note that by employing the three structure.learning.algorithm, structure.learning.algorithm2, structure.learning.algorithm3 arguments and their corresponding structure.learning.args.list* counterparts, many different configurations can be used for the structure learning process, e.g. by using grow-shrink for D nodes with distance set to 1, then injecting the left nodes using hill-climbing without distance restriction.
fix.intermediate, if set to TRUE, will forbid the creation of new arcs between nodes that were present in the previous learning step. E.g. if structure.learning.steps = c("local", "global\-past"), no new arcs between D nodes will be created in the second step, as the first DAG will be considered finished. If set to FALSE, the previous step DAG will be kept, but the next learning algorithm could create new arcs between D nodes over the first one.

Forbidding or Forcing Arcs force.DD, forbid.GG, forbid.DD, forbid.DtoG, force.closest.GD, forbid.GD, fix.intermediate, structure.learning.steps allow for introducing constraints to the structure learning algorithm. The user might also combine them with structure.learning.args.list$whitelist and structure.learning.args.list$blacklist. As whitelist has priority over blacklist, i.e. an arc placed in both will always be present in the DAG, they provide maximum flexibility. Bearing the priority of the whitelist, force.closest.GD = TRUE and forbid.GD = TRUE will, for example, forbid the placement of aditional arcs beyond those specified as the closest G-D.

When manually specifying a whitelist or blacklist through structure.learning.args.list, beware of the naming convention. It overrides the names and marks them as either "D.X" or "G.X", predictand and predictor nodes, respectivelly. A plot of a dummy network using plotDBN() is may help.