Package {gdxtools}

gdxtools: manipulate 'GDX' files

Description

Read and write 'GDX' files ('GAMS' data exchange) using the 'GAMS'-maintained gamstransfer package as the underlying backend. Symbols are returned as plain data frames with domain columns plus a value column, preserving the API of earlier (gdxrrw-backed) versions.

Author(s)

Maintainer: Laurent Drouet ldrouet@pm.me

Authors:

• Laurent Drouet ldrouet@pm.me

See Also

Useful links:

• https://github.com/lolow/gdxtools

• Report bugs at https://github.com/lolow/gdxtools/issues

Return the list of all items

Description

Return the list of all items

Usage

all_items(x, ...)

Arguments

Value

A named list with four character vectors of symbol names: variables, parameters, sets and equations.

Author(s)

Laurent Drouet

Extract a list of items from many GDX

Description

Extract a list of items from many GDX

Usage

batch_extract(items, files = NULL, gdxs = NULL, ...)

Arguments

Value

A named list with one data.frame per requested item, each the row-bind of that item extracted from every file with a gdx column identifying the source file.

Author(s)

Laurent Drouet

Examples

 f1 <- tempfile(fileext = ".gdx")
 f2 <- tempfile(fileext = ".gdx")
 write.gdx(f1, list(myparam = data.frame(i = c("a", "b"), value = 1:2)))
 write.gdx(f2, list(myparam = data.frame(i = c("a", "b"), value = 3:4)))
 allparam <- batch_extract("myparam", files = c(f1, f2))

Extract data from a gdx

Description

Extract data from a gdx

Usage

extract(x, ...)

Arguments

Value

A data.frame; see extract.gdx for the column layout and attributes.

Extract parameter or variable data from the gdx file

Description

Extract parameter or variable data from the gdx file

Usage

## S3 method for class 'gdx'
extract(x, item, field = "l", addgdx = FALSE, ...)

Arguments

Value

A data.frame with one character column per domain index plus a numeric value column (parameters, variables and equations); sets have no value column. A gams attribute carries the symbol's description text, and addgdx = TRUE adds a gdx column with the source filename.

Author(s)

Laurent Drouet

Examples

 f <- tempfile(fileext = ".gdx")
 write.gdx(f, list(travel_cost = data.frame(city = c("paris", "lyon"),
                                             value = c(12, 7))))
 mygdx <- gdx(f)
 travel_cost <- mygdx["travel_cost"]
 travel_cost <- extract(mygdx, "travel_cost")

Run the GAMS executable

Description

Thin wrapper around system2("gams", ...). Returns the integer exit status from GAMS.

Usage

gams(gmsAndArgs)

Arguments

Value

exit status (integer)

GDX file

Description

Constructs a gdx object backed by a gamstransfer::Container. By default the file is opened in lazy mode: only symbol metadata (names, dimensions, domains, descriptions) is read up front. Each symbol's records are loaded on first access via [.gdx / extract() and then cached on the container for subsequent calls. Pass lazy = FALSE to read everything eagerly (legacy 1.0.0 behavior).

Usage

gdx(filename, lazy = TRUE, ...)

Arguments

Value

An object of class gdx: an S3 list holding the live gamstransfer::Container(s) and per-type symbol metadata (variables, parameters, sets, equations data.frames with name, text and dim columns).

Author(s)

Laurent Drouet

Examples

 f <- tempfile(fileext = ".gdx")
 write.gdx(f, list(demand = data.frame(city = c("paris", "lyon"),
                                        value = c(50, 20))))
 mygdx <- gdx(f)                  # lazy by default
 mygdx["demand"]                  # triggers a targeted read
 eager <- gdx(f, lazy = FALSE)

GAMS sysdir locator (kept for backward compatibility)

Description

Pre-1.0 gdxtools relied on the gdxrrw API and required the user to point it at a GAMS install. The gamstransfer backend is self-contained and does not need this. igdx now simply discovers gams on the PATH (or uses the directory the user supplies) and returns it; calling it has no side effect on gdx I/O.

Usage

igdx(gamsSysDir = NULL, silent = FALSE, returnStr = FALSE)

Arguments

Value

the discovered GAMS system directory, or "" if none found

Eagerly load records for one or more symbols

Description

Lazy-opened gdx objects defer reading records until first access. When you know up front which symbols you will use (or you want to amortize the I/O cost), call load_records() to read them in a single batched gamstransfer::Container$read() call.

Usage

load_records(x, symbols = NULL)

Arguments

Value

x invisibly. Records are stored on the underlying container.

Author(s)

Laurent Drouet

Examples

 f <- tempfile(fileext = ".gdx")
 write.gdx(f, list(a = data.frame(i = c("x", "y"), value = 1:2),
                   b = data.frame(i = c("x", "y"), value = 3:4)))
 g <- gdx(f)
 load_records(g, c("a", "b"))
 g["a"]  # already cached, no I/O

Write a list of parameters / sets / variables to a GDX

Description

Builds a gamstransfer::Container from the supplied data and writes it to file. Variables can be given as separate level / lower / upper data.frames (keyed by the same variable name across the three lists); missing entries fall back to the gamstransfer defaults (level 0, lower -Inf, upper +Inf for free variables).

Usage

write.gdx(
  file,
  params = list(),
  vars_l = list(),
  vars_lo = list(),
  vars_up = list(),
  sets = list(),
  removeLST = TRUE,
  usetempdir = TRUE,
  digits = 16,
  compress = FALSE,
  na = c("drop", "keep", "error"),
  dup = c("first", "last", "error")
)

Arguments

Value

Invisibly returns 0; called for the side effect of writing the gdx file at file.

Author(s)

Laurent Drouet

Examples

 param1 <- data.frame(x = c('1', '2'), value = 1:2)
 param2 <- data.frame(a = c('london', 'paris'), value = c(50, 0.2))
 write.gdx(tempfile(fileext = ".gdx"),
           list(param1 = param1, param2 = param2))

Write parameters and sets to a gdx (alias of write.gdx for backward compatibility)

Description

Historically this was a faster path that bypassed the GAMS process used by the legacy write.gdx. With the gamstransfer backend both functions use the same fast path; this entry point is kept for code that calls it explicitly.

Usage

write2.gdx(
  file,
  params = list(),
  sets = list(),
  na = c("drop", "keep", "error"),
  dup = c("first", "last", "error")
)

Arguments

Value

Invisibly returns 0; called for the side effect of writing the gdx file at file.

Author(s)

Laurent Drouet