Modify several scenarios at once by replacing, deleting or adding nodes (e.g. events) in scenario .xml files.
The path to the 'Scenarios' folder
A character vector with the scenarios to be processed or "all"
The name of the xml file to use as template for the new nodes
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.
path.scenarios=NULL, an interactive dialog box is used to select
the path where the scenario xml files are located.
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
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
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
csv.in as a character vector. The file must have the following
headings: nodes, identifier, attribute, mode, ref, ref_identifier, and
scenarios.batch.modifier will parse the file and use
these columns as arguments. See
package="HexSimR") for an example file.
The column with heading nodes is the path to the node to be searched
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
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
# 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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.