Package {CLDedgelister}

CLDedgelister: Import System-Dynamics Models and Convert Them to Edge Lists

Description

Imports causal / system-dynamics models from Vensim, Stella / iThink, Powersim Studio, AnyLogic and GoldSim, and converts them into a two-column INPUT -> OUTPUT edge list. Use model_to_edgelist from the console, or the RStudio addin cld_edgelist_addin.

Author(s)

Maintainer: Taddias Prince Mpofu princetaddy@gmail.com [copyright holder]

Authors:

• Taddias Prince Mpofu princetaddy@gmail.com [copyright holder]

• Mawuko Bonoukpoe Joel Sokame

• Frank Chidawanyika

• Joel Cornelius Runyu

• Marc Marin Agbodjan

Import a model and convert it to an edge list (RStudio addin)

Description

Opens a small window to pick a Vensim, Stella, Powersim, AnyLogic or GoldSim model, preview the resulting INPUT -> OUTPUT edge list, and optionally save it as CSV or Excel. The chosen edge list is returned as a data.frame when the gadget closes, so it can be captured with el <- cld_edgelist_addin().

Usage

cld_edgelist_addin()

Value

A data.frame of INPUT/OUTPUT edges (invisibly NULL if cancelled). When launched from the RStudio Addins menu the result is returned to the console.

Supported model formats

Description

Supported model formats

Usage

cld_formats()

Value

A character vector of the format labels the package understands.

Examples

cld_formats()

Detect GoldSim's native binary model

Description

Detect GoldSim's native binary model.

Usage

looks_like_goldsim_binary(path)

Arguments

Details

Formats are told apart by CONTENT rather than by extension. Powersim and GoldSim both use .sim for different formats: Powersim writes an OLE2 compound document and GoldSim does not, so each file reaches the right reader.

Value

A single logical value.

See Also

model_to_edgelist

Detect a Powersim Studio project file

Description

Detect a Powersim Studio project file. A .sip/.sim is an OLE2 compound document holding IFF-chunked streams, not XMILE. Variable names decode cleanly from the FTXT chunks; the links do not, because Powersim indirects their endpoints through an undocumented symbol table. Export to XMILE from Powersim Studio for a model that can be read exactly.

Usage

looks_like_powersim(path)

Arguments

Value

A single logical value.

Detect a legacy Stella binary model

Description

Before XMILE, isee systems saved models in a proprietary binary format whose files begin with the signature TL2STM2. Such a file is not XML and cannot be read by an XML parser, so it must be routed to parse_stm rather than to the XMILE reader.

Usage

looks_like_stm(path)

Arguments

Value

A single logical value: TRUE when the file carries the legacy Stella binary signature TL2STM2, otherwise FALSE.

See Also

parse_stm

Examples

p <- tempfile(fileext = ".stmx")
writeLines("<xmile><model/></xmile>", p)
looks_like_stm(p)

Convert a system-dynamics model file to an edge list

Description

Reads a model from Vensim, Stella / iThink, Powersim Studio, AnyLogic or GoldSim and returns a two-column data.frame of INPUT (cause) and OUTPUT (effect) links - the same edge list produced by the SDM Network Analyzer.

Usage

model_to_edgelist(path, format = NULL)

Arguments

Value

A data.frame with columns INPUT and OUTPUT. Node diagram positions, when available, are attached as attr(x, "positions").

Examples

# Convert the bundled example Vensim model to an edge list
mdl <- system.file("extdata", "example_model.mdl", package = "CLDedgelister")
el <- model_to_edgelist(mdl)
head(el)

Convert a model file and write the edge list to disk

Description

Convert a model file and write the edge list to disk

Usage

model_to_edgelist_file(path, out_path = NULL, format = NULL)

Arguments

Value

(invisibly) the edge list data.frame.

Examples

mdl <- system.file("extdata", "example_model.mdl", package = "CLDedgelister")
out <- tempfile(fileext = ".csv")
model_to_edgelist_file(mdl, out)

Read a compressed AnyLogic project (.alpx)

Description

Read a compressed AnyLogic project (.alpx).

Usage

parse_alpx(path)

Arguments

Details

Formats are told apart by CONTENT rather than by extension. Powersim and GoldSim both use .sim for different formats: Powersim writes an OLE2 compound document and GoldSim does not, so each file reaches the right reader.

Value

A two-column data.frame of INPUT and OUTPUT.

See Also

model_to_edgelist

Read a Powersim Studio project (.sip / .sim)

Description

Read a Powersim Studio project (.sip / .sim). A .sip/.sim is an OLE2 compound document holding IFF-chunked streams, not XMILE. Variable names decode cleanly from the FTXT chunks; the links do not, because Powersim indirects their endpoints through an undocumented symbol table. Export to XMILE from Powersim Studio for a model that can be read exactly.

Usage

parse_powersim(path)

Arguments

Value

A two-column data.frame of INPUT and OUTPUT, empty when no links could be recovered, with the variables in the variables attribute.

Read a legacy Stella binary model (.STM / .ITM)

Description

Reads the pre-XMILE binary format used by Stella and iThink, whose files begin with the signature TL2STM2.

Usage

parse_stm(path)

Arguments

Details

Variable names and equations both come out of the binary cleanly. The mapping BETWEEN them does not: the name records and the equation records are not interleaved one-for-one, and the remaining links are held in an undocumented binary dependency section. Measured on two published models, only 22% and 42% of variables could be matched to their own equation.

Pairing them by proximity anyway yields a network that looks plausible and is partly wrong, with links attributed to the wrong variable. This reader therefore returns an edge list only when the pairing is unambiguous for the great majority of variables, and otherwise stops with an explanation.

To convert such a model, open it in Stella or iThink and use File > Save As to write a .stmx (XMILE) file, which is read exactly.

Value

A two-column data.frame with columns INPUT (cause) and OUTPUT (effect), one row per link.

See Also

looks_like_stm, model_to_edgelist

Examples

p <- tempfile(fileext = ".STM")
writeBin(c(charToRaw("TL2STM2"), as.raw(rep(0, 60))), p)
looks_like_stm(p)

try(parse_stm(p))

Read a Vensim XML model (.vmfx)

Description

Read a Vensim XML model (.vmfx).

Usage

parse_vmfx(path)

Arguments

Details

Formats are told apart by CONTENT rather than by extension. Powersim and GoldSim both use .sim for different formats: Powersim writes an OLE2 compound document and GoldSim does not, so each file reaches the right reader.

Value

A two-column data.frame of INPUT and OUTPUT.

See Also

model_to_edgelist

Read the links from a Powersim Studio diagram

Description

Read the links from a Powersim Studio diagram.

Usage

powersim_links(path)

Arguments

Details

Formats are told apart by CONTENT rather than by extension. Powersim and GoldSim both use .sim for different formats: Powersim writes an OLE2 compound document and GoldSim does not, so each file reaches the right reader.

Value

A two-column data.frame of INPUT and OUTPUT, empty when the file carries no readable diagram.

See Also

model_to_edgelist

Read variable names from a Powersim Studio project

Description

Read variable names from a Powersim Studio project. A .sip/.sim is an OLE2 compound document holding IFF-chunked streams, not XMILE. Variable names decode cleanly from the FTXT chunks; the links do not, because Powersim indirects their endpoints through an undocumented symbol table. Export to XMILE from Powersim Studio for a model that can be read exactly.

Usage

powersim_variables(path)

Arguments

Value

A character vector of variable names.