scenarios.batch.modifier: Batch modification of scenarios
In carlopacioni/HexSimR: An R Package For Post HexSim Simulation Analysis

Description Usage Arguments Details Examples

Modify several scenarios at once by replacing, deleting or adding nodes (e.g. events) in scenario .xml files.

scenarios.batch.modifier(
  path.scenarios = NULL,
  scenarios = "all",
  xml.template = NULL,
  csv.in
)

`path.scenarios`	The path to the 'Scenarios' folder
`scenarios`	A character vector with the scenarios to be processed or "all"
`xml.template`	The name of the xml file to use as template for the new nodes
`csv.in`	The name of the .csv file in the "Scenarios" folder with the information on the nodes that need to be modified (or checked in case of xml.cond.replacement)

If several scenarios have been developed in HexSim and later the user realises that there are some modifications that need to be applied to several or all of them, this function can help automate this task. It involves generating a scenario with the correct/new events and parameters. This scenario is used then as template and the nodes that need to be added, replaced or deleted are identified using a .csv file. Some setting up is required and it may not be worthwhile for only one or two scenarios. To use this function some understanding of the xml file structure in HexSim is necessary. The easiest is to open the xml file and have a look at the structure. Using a source code editor like Notepad++ (that colour-code different element of the text based on the language used) can help to understand the structure. Briefly, each of the settings and parameters in HexSim is set by a node in the xml file. Some nodes have a unique identifier, which can be an attribute (generally name="attribute_value"), or a text element value (e.g. <name> node_name </name>). To this end, identifiers are considered element that make the node unique. For example, accumulate events have all the same structure, but they can be identified by the value given to the node <name>. On the contrary, there are nodes that are unique and can be simply identified by the node's name. One example of such nodes is <initializationSpatialData>, which is unique, so a search in the xml file for the path: "/scenario/population/initializationSpatialData" will return one node only. From a practical point of view, the easiest way to work out of to complete the setting up for this function is to create or modify a scenario with the correct events/parameters. Save it and then comparing this with one of the one that needs to be modified using, for example, the plug in "compare" in Notepad++, or Winmerge (on Windows). For more information see the vignette: Latin Hypercube Sampling and (batch) modification of scenarios and maps.

If path.scenarios=NULL, an interactive dialog box is used to select the path where the scenario xml files are located.

If scenarios="all" (default), all scenarios are processed, otherwise it is possible to select a subset of scenarios using a character vector, e.g. scenarios=c("scen1", "scen2"). Note: when a xml.template is passed, this is assumed to be in the path.scenarios directory and it is removed from the list of scenarios to be modified.

A back up of the folder path.scenarios is copied in the the folder "Scenarios_bkup", one level up from path.scenarios.

The .csv file essentially provides the information on how to locate the nodes that need to be modified, and what type of actions need to be carried out.The .csv must be located in the scenario folder and the name should be passed with csv.in as a character vector. The file must have the following headings: nodes, identifier, attribute, mode, ref, ref_identifier, and ref_attribute. scenarios.batch.modifier will parse the file and use these columns as arguments. See system.file("extdata", "test_csv.csv", package="HexSimR") for an example file.

The column with heading nodes is the path to the node to be searched in the xml.template file, except when the mode is "delete", in which case the nodes are searched in the scenario file and then deleted. The path starts at the root of the xml file ("scenario") and progresses until the node's name or identifier. It must start with a "/", and must not have a "/" at the end. For example, for an accumulator, the path in the column "nodes" would be: "/scenario/population/accumulators/accumulator/name".

identifier is used to indicate whether the node has an identifier. If it does (e.g. name="attribute_value"), the name (or the value if an attribute) of the identifier needs to be in this column (e.g. attribute_value), otherwise FALSE must be used.

attribute indicates whether the identifier is an attribute (TRUE) or not (FALSE).

mode indicates the type of action that needs to be performed. Possible options are "add", "before", "after", "replace" or "delete". If "add" the node is added as last child of the parent node. If the node needs to be added in a specific position (events generally do), "before" and "after" should be used to indicate the position respect to the ref node (i.e. whether the new node goes before or after the node ref. Note that the ref node is searched in the scenario file, not the xml.template. If the option "delete" is used, the node is searched and deleted from the scenario file. When "replace" is used, the ref node must be provided, even when the node is the same. This is because there might be situations where what it is being changed is the name of the node. In these cases, scenarios.batch.modifier would not find the original node in the scenario file.

ref needs to be passed when the options "before", "after" or "replace" are used in mode. When not relevant, NA is used. When ref is used, then a search is performed in the scenario xml file and the fields ref_identifier and ref_attribute must also be passed when relevant. ref_identifier and ref_attribute have the same meaning as identifier and attribute, but they refer to the ref node. Use FALSE when these are not relevant.

# locate and copy example files
 new <- system.file("extdata", "MRVC_4BaitYr_ThreeCells.xml", package="HexSimR")
 old <- system.file("extdata", "MRVC_4BaitYr_ThreeCells_old.xml", package="HexSimR")
 csv.in <- system.file("extdata", "test_csv.csv", package="HexSimR")
 testFolder <- tempdir(check = TRUE)
 file.copy(c(new, old, csv.in), testFolder)
 
 XMLTest <- scenarios.batch.modifier(
   path.scenarios=testFolder,
   scenarios="MRVC_4BaitYr_ThreeCells_old.xml", 
   xml.template="MRVC_4BaitYr_ThreeCells.xml",
   csv.in="test_csv.csv")
 
 # Clean up
 files <- list.files(testFolder, full.names=TRUE)
 file.remove(files)
 unlink(file.path(dirname(testFolder), '/Scenarios_bkup'), recursive=TRUE)