Type:	Package
Title:	'GAMS' Modularization Support Package
Version:	0.31.2
Date:	2024-06-27
Description:	A collection of tools to create, use and maintain modularized model code written in the modeling language 'GAMS' (https://www.gams.com/). Out-of-the-box 'GAMS' does not come with support for modularized model code. This package provides the tools necessary to convert a standard 'GAMS' model to a modularized one by introducing a modularized code structure together with a naming convention which emulates local environments. In addition, this package provides tools to monitor the compliance of the model code with modular coding guidelines.
Imports:	dplyr, rlang, stringr, withr, yaml, filelock, stats
Suggests:	covr, curl, magclass, qgraph, testthat, callr
URL:	https://github.com/pik-piam/gms, https://doi.org/10.5281/zenodo.4390032
BugReports:	https://github.com/pik-piam/gms/issues
License:	BSD_2_clause + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.1
Config/Keywords:	tool
NeedsCompilation:	no
Packaged:	2024-06-28 11:09:32 UTC; dietrich
Author:	Jan Philipp Dietrich [aut, cre] (affiliation: Potsdam Institute for Climate Impact Research), David Klein [aut] (affiliation: Potsdam Institute for Climate Impact Research), Anastasis Giannousakis [aut], Felicitas Beier [aut] (affiliation: Potsdam Institute for Climate Impact Research), Johannes Koch [aut] (affiliation: Potsdam Institute for Climate Impact Research), Lavinia Baumstark [aut] (affiliation: Potsdam Institute for Climate Impact Research), Mika Pflüger [aut], Oliver Richters [aut] (affiliation: Potsdam Institute for Climate Impact Research)
Maintainer:	Jan Philipp Dietrich <dietrich@pik-potsdam.de>
Repository:	CRAN
Date/Publication:	2024-06-29 06:50:10 UTC

gms: 'GAMS' Modularization Support Package

Description

A collection of tools to create, use and maintain modularized model code written in the modeling language 'GAMS' (https://www.gams.com/). Out-of-the-box 'GAMS' does not come with support for modularized model code. This package provides the tools necessary to convert a standard 'GAMS' model to a modularized one by introducing a modularized code structure together with a naming convention which emulates local environments. In addition, this package provides tools to monitor the compliance of the model code with modular coding guidelines.

Author(s)

Maintainer: Jan Philipp Dietrich dietrich@pik-potsdam.de (ORCID) (Potsdam Institute for Climate Impact Research)

Authors:

• David Klein (Potsdam Institute for Climate Impact Research)

• Anastasis Giannousakis

• Felicitas Beier (Potsdam Institute for Climate Impact Research)

• Johannes Koch (Potsdam Institute for Climate Impact Research)

• Lavinia Baumstark (Potsdam Institute for Climate Impact Research)

• Mika Pflüger

• Oliver Richters (Potsdam Institute for Climate Impact Research)

See Also

Useful links:

• https://github.com/pik-piam/gms

• doi: 10.5281/zenodo.4390032

• Report bugs at https://github.com/pik-piam/gms/issues

GAMScodeFilter

Description

Cleans GAMS code supplied from empty lines and comments.

Usage

GAMScodeFilter(x)

Arguments

Value

The cleaned GAMS code

Author(s)

Jan Philipp Dietrich

See Also

readDeclarations

Examples

GAMScodeFilter(c("","*comment","a=12;","","b=13;"))

checkAppearance

Description

Checks for all declared objects in which parts of the model they appear and calculates the type of each object (core object, interface object, module object of module xy,...)

Usage

checkAppearance(x, capitalExclusionList = NULL)

Arguments

Value

A list with four elements: appearance, setappearance, type and warnings. Appearance is a matrix containing values which indicate whether an object appears in a part of the code or not (e.g. indicates whether "vm_example" appears in realization "on" of module "test" or not.). 0 means that it does not appear, 1 means that it appears in the code and 2 means that it appears in the not_used.txt. setappearance contains the same information but for sets instead of other objects. Type is a vector containing the type of each object (exluding sets). And warnings contains a list of warnings created during that process.

Author(s)

Jan Philipp Dietrich

See Also

codeCheck,readDeclarations

checkDescription

Description

Checks whether all Declarations of a GAMS code come with a Description, throws out a warning in case of a missing description.

Usage

checkDescription(x, w = NULL)

Arguments

Value

vector of warnings

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

checkNoTabs

Description

Check all files (also in subdirectories) matching the given pattern for tabs. Will throw an error with a list of files where tabs were found if any.

Usage

checkNoTabs(pattern, exclude = NULL, excludeFolders = NULL)

Arguments

Value

Invisibly, the list of files that were checked.

Author(s)

Pascal Sauer

Examples

## Not run: 
gms::checkNoTabs(pattern = "\\.(R|Rprofile|gms|cfg|bib)$",
                 excludeFolders = c("output", "renv", ".git"))
gms::checkNoTabs(utils::glob2rx("*.R"))

## End(Not run)

checkSwitchAppearance

Description

Checks for all declared switches in which parts of the model they appear and calculates the type of each object (core object, interface object, module object of module xy,...)

Usage

checkSwitchAppearance(code)

Arguments

Value

A list with three elements: switches, appearance and type. Switches is a vector containing all switches. The names of the vector contain the information where the switch is set. Appearance is a matrix containing values which indicate whether an object appears in a part of the code or not (e.g. indicates whether "vm_example" appears in realization "on" of module "test" or not.). 0 means that it does not appear, 1 means that it appears in the code and 2 means that it appears in the not_used.txt. Type is a vector containing the type of each object.

Author(s)

Jan Philipp Dietrich

See Also

codeCheck,readDeclarations,codeExtract,checkAppearance

Check config

Description

Checks a model configuration file for consistency by comparing it to a reference config file and the given module structure of the model. The function will throw out an error if settings are missing in the config which exist in the reference config, of if settings are set in the config which do not exist in the reference config file or if a realization is chosen for a module which does not exist, not allowed setting combinations.

Usage

check_config(
  icfg,
  reference_file = "config/default.cfg",
  modulepath = "modules/",
  settings_config = NULL,
  extras = NULL,
  saveCheck = FALSE
)

Arguments

Value

The checked config as a config list ready for further usage.

Author(s)

Jan Philipp Dietrich, Lavinia Baumstark

See Also

getModules

chooseFromList

Description

Allows the user to select single or multiple items from a list. Entries can be selected based on individual choice, groups, regex or all.

Usage

chooseFromList(
  theList,
  type = "items",
  userinfo = NULL,
  addAllPattern = TRUE,
  returnBoolean = FALSE,
  multiple = TRUE,
  userinput = FALSE,
  errormessage = NULL
)

Arguments

Value

list or character vector, either a boolean with same length as theList or only the selected items.

Author(s)

Oliver Richters

Examples

 ## Not run: 
    chooseFromList(
      theList = c(Letter = "A", Letter = "B", Number = "1", Number = "2"),
      type = "characters",
      userinfo = "Please don't select B, it hurts.",
      returnBoolean = FALSE,
      multiple = TRUE)
  
## End(Not run)

codeCheck

Description

Checks GAMS code for consistency. Throws out warnings if something is wrong in the code and returns a list containing the interfaces of each module of the code.

Usage

codeCheck(
  path = ".",
  modulepath = "modules",
  core_files = c("core/*.gms", "main.gms"),
  returnDebug = FALSE,
  interactive = FALSE,
  test_switches = TRUE,
  strict = FALSE,
  details = FALSE
)

Arguments

Details

Additional settings can be provided via a yaml file ".codeCheck" in the main folder of the model. Currently supported settings are: - capitalExclusionList: a list of names that should be ignored when checking for unified capitalization of variables

Value

A list of all modules containing the interfaces for each module. Or more detailed output if either details or returnDebug is set to TRUE.

Author(s)

Jan Philipp Dietrich

See Also

codeExtract,readDeclarations

Examples

# check code consistency of dummy model
codeCheck(system.file("dummymodel", package = "gms"))

codeExtract

Description

Returns aggregated and cleaned GAMS code together with declaration matrix

Usage

codeExtract(codeFiles, name)

Arguments

Value

A list with two elements: code and declarations. Code contains the cleaned up gams code and declarations contains the declarations matrix as returned by readDeclarations

Author(s)

Jan Philipp Dietrich

See Also

codeCheck,readDeclarations

convert.modularGAMS

Description

Converts modular GAMS code from an older modular definition to the newest one

Usage

convert.modularGAMS(path = ".", modulepath = "modules/")

Arguments

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

copy_input

Description

Function to copy input files to their destination folders

Usage

copy_input(x, sourcepath, suffix = NULL, move = FALSE)

Arguments

Author(s)

Jan Philipp Dietrich, David Klein

delete_olddata

Description

Delete data provided in mapping

Usage

delete_olddata(x)

Arguments

Author(s)

Jan Philipp Dietrich, David Klein

Download and unpack compressed data from repositories

Description

Downloads a list of tgz files from a list of repos and unpacks them

Usage

download_distribute(
  files,
  repositories = list(`/p/projects/rd3mod/inputdata/output` = NULL),
  modelfolder = ".",
  additionalDelete = NULL,
  debug = FALSE,
  stopOnMissing = FALSE
)

Arguments

Value

Information about the download process in form of a data.frame with data sets as row names and repositories (where it was downloaded from) and corresponding md5sum as columns

Author(s)

Jan Philipp Dietrich, Lavinia Baumstark

Download and unpack compressed data from repositories

Description

Downloads a list of tgz files from a list of repos and unpacks them. If a file is no .tgz-file it will be only downloaded.

Usage

download_unpack(
  input,
  targetdir = "input",
  repositories = NULL,
  debug = FALSE,
  unpack = TRUE,
  stopOnMissing = FALSE
)

Arguments

Value

Information about the download process in form of a data.frame with data sets as row names and repositories (where it was downloaded from) and corresponding md5sum as columns

Author(s)

Jan Philipp Dietrich

fulldataOutput

Description

Creates GAMS code which stores automatically the levels, bounds and marginals of all equations and variables in time depending parameters.

Usage

fulldataOutput(
  declarations_file = "declarations.gms",
  definitions_file = "postsolve.gms",
  warn = TRUE,
  types = c("level", "marginal"),
  ignore = "_dummy$",
  loopset = "t"
)

Arguments

Author(s)

Jan Philipp Dietrich, Felicitas Beier

See Also

readDeclarations,replace_in_file

getLine

Description

Get one line of user input regardless of whether running interactively or not (via Rscript). (base::readline does not wait for user input when running via Rscript.)

Usage

getLine()

Value

The user input as a string.

getModules

Description

Extract module information of a GAMS model.

Usage

getModules(modulepath)

Arguments

Value

A matrix containing the different modules with name, corresponding module number and corresponding realizations

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

get_info

Description

Function to extract information from info.txt

Usage

get_info(file, grep_expression, sep, pattern = "", replacement = "")

Arguments

Author(s)

Jan Philipp Dietrich, David Klein

getfiledestinations

Description

Create file2destination mapping based on information from the model, ignoring top-level directories listed in .gitignore.

Usage

getfiledestinations(path = ".", ignoreFolders = "renv")

Arguments

Author(s)

Jan Philipp Dietrich, David Klein

interfaceplot

Description

Creates an interface plot of a modular model using qgraph and returns the interface information.

Usage

interfaceplot(
  x = ".",
  modules_to_include = NULL,
  modules_to_exclude = NULL,
  links_to_include = NULL,
  links_to_exclude = NULL,
  items_to_include = NULL,
  items_to_exclude = NULL,
  items_to_display = NULL,
  default_groups = list(default1 = list(name = "core", nodes = "core", color = "black",
    shape = "rectangle"), default2 = list(name = "modules", nodes = NULL, color =
    "#6c9ebf", shape = "ellipse")),
  highlight_groups = NULL,
  max_length_node_names = NULL,
  add_nodeName_legend = FALSE,
  max_num_edge_labels = NULL,
  max_num_nodes_for_edge_labels = 30,
  ...
)

Arguments

Details

What modules (=nodes), links (=edges) and items (=what is passed along the edges) are taken into account when creating the plot can be fine-tuned with the "_include", "_exclude" arguments.

The "default"- and "highlight_groups" arguments control the formatting (and also the composition through "highlight_group$edges_to_ignore"). Groups in qqgraph are a way of clustering nodes together. The default formatting of the plot is defined with the "default_groups" argument. On top of that additional groups can be defined with the "highlight_groups" argument.

The rest of the arguments are pretty self-explanatory. Just remember that qgraph arguments can be passed on as well! Useful ones include: fade=T/F, legend=T/F, legend.cex (size of the legend font), GLratio (graph/legend size ratio, edge.label.cex (size of the edge label font)).

Value

A tibble with the edge list and interface items.

Author(s)

Johannes Koch

See Also

codeCheck,qgraph

is.modularGAMS

Description

Checks whether a folder seems to contain modular GAMS code or not.

Usage

is.modularGAMS(path = ".", version = FALSE, modulepath = "modules/")

Arguments

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

Examples

is.modularGAMS(system.file("dummymodel",package="gms"))

Load Config

Description

Load config in YAML format as written via saveConfig.

Usage

loadConfig(cfg)

Arguments

Details

To read in the default configuration (stored as R list in default.cfg or in a gams file), use readDefaultConfig instead.

Author(s)

Jan Philipp Dietrich

See Also

saveConfig

Examples

cfg <- list(input = c(data1 = "blub.tgz", data2 = "bla.tgz"), mode = "default")
yml <- saveConfig(cfg)
loadConfig(yml)

Function to detect R package dependencies

Description

This function analyzes a model folder and all subfolders and searches for library and require statements.

Usage

model_dependencies(mainfolder = ".")

Arguments

Value

A list of dependencies sorted by appearances

Author(s)

Jan Philipp Dietrich

Model lock/unlock

Description

Lock the model to coordinate multiple processes accessing the model. This is necessary if you change files within the model and have to avoid that another process reads from your half-written changes in the mean time. model_lock creates an exclusive lock on the given file and returns a lock id. When the lock id is handed to model_unlock the lock is dropped again, and another process can take the lock. The lock is also dropped when the lock id goes out of scope and is garbage collected in R or when the R process terminates or crashes. However, it is good practice to explicitly call model_unlock when you don't need the lock anymore. If you want to check for informational purposes if the model is currently locked by another process, you can use the is_model_locked() function. Note however that you should never use is_model_locked() to coordinate access to the model folder. The return value of is_model_locked() is only a snapshot at the time when the function is run. Note additionally that is_model_locked() checks if the model is locked by another process. If you currently hold the lock of the model yourself, it will return FALSE.

Usage

model_lock(folder = ".", file = ".lock", timeout1 = 12, timeout2 = NULL,
check_interval = NULL, oncluster = NULL)
model_unlock(id, folder = NULL, file = NULL, oncluster = NULL)
is_model_locked(folder = ".", file = ".lock")

Arguments

Value

model_lock returns the lock id which is needed to identify the lock in model_unlock.

Author(s)

Jan Philipp Dietrich, David Klein, Mika Pflüger

See Also

check_config

Examples

#lock folder
id <- model_lock(tempdir())

#unlock folder
model_unlock(id)

Create a Module skeleton

Description

This function creates you a module skeleton which you can use to easily create your own modules.

Usage

module.skeleton(
  number,
  name,
  types,
  modelpath = ".",
  modulepath = "modules/",
  includefile = "modules/include.gms",
  version = is.modularGAMS(modelpath, version = TRUE)
)

Arguments

Note

Module phases are automatically detected checking the main code of the model, but not checking code in modules. If you want to use additional phases which are only included within a module, you need to specify them manually by adding a comment into your gams code indicating that there is an additional phase. The syntax is "* !add_phase!: <phase>", e.g. "* !add_phase!: new_phase"

Author(s)

Jan Philipp Dietrich

Examples

# copy dummymodel to temporary directory and add new module "bla"
file.copy(system.file("dummymodel",package="gms"),tempdir(), recursive = TRUE)
model   <- paste0(tempdir(),"/dummymodel")
module.skeleton(number="03", name="bla", types=c("on","off"), modelpath=model)

modules_interfaceplot

Description

Function that applies interfaceplot for a whole model and all its modules.

Usage

modules_interfaceplot(
  x = ".",
  modulepath = "modules",
  filetype = "png",
  targetfolder = NULL,
  writetable = TRUE,
  includeCore = FALSE,
  ...
)

Arguments

Value

A list with interface tables for each module

Author(s)

Jan Philipp Dietrich

See Also

codeCheck,interfaceplot

path

Description

Small function to build a consistent path-string based on folder, filename and filetype. The function makes sure that slashes and the dot for the file ending are set correctly (you can supply your folder name either with or without a tailing slash in it. It does not matter.

Usage

path(..., ftype = NULL)

Arguments

Value

A string containing the path combined of folder, filename and filetype

Author(s)

Jan Philipp Dietrich

Publish data in a repository

Description

Downloads a list of tgz files from a list of repos, merge them and publish it on another server

Usage

publish_data(
  input,
  name = NULL,
  target = Sys.getenv("PUBLISH_DATA_TARGET", unset = "."),
  ...
)

Arguments

Author(s)

Jan Philipp Dietrich

See Also

download_unpack,tardir

readDeclarations

Description

Reads all declarations given in a GAMS code and returns them.

Usage

readDeclarations(
  file,
  unlist = TRUE,
  types = c("scalar", "(positive |)variable", "parameter", "table", "equation", "set")
)

Arguments

Value

Either a list of declared objects or a matrix containing object name, the sets the object depends on and the description.

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

readDefaultConfig

Description

Reads the default configuration of the model. Uses default.cfg or main.cfg as the source as appropriate. To read a configuration from YAML format, use loadConfig instead.

Usage

readDefaultConfig(path)

Arguments

Value

A vector of parameter values and their names.

Author(s)

Mika Pflüger

See Also

loadConfig

readFileOrVector

Description

Input: a file name or a character vector. Output: a character vector of the contents of the file, or the character vector unchanged.

Usage

readFileOrVector(file)

Arguments

Value

A character vector of the inputs of the file.

Author(s)

Mika Pflüger

readParameterValues

Description

Read values of given parameters from a given GAMS code section.

Usage

readParameterValues(code, parameters)

Arguments

Details

The GAMS code section should contain statements of the form parameter = value; for all the given parameters.

Value

A vector of values the parameters are set to with parameter names as names.

Author(s)

Mika Pflüger

See Also

readDeclarations

readSetglobals

Description

Reads all setglobals given in a GAMS code and returns them.

Usage

readSetglobals(file)

Arguments

Value

A vector of values the setglobal variables are set to with setglobal variables as names.

Author(s)

Jan Philipp Dietrich

See Also

readDeclarations

readSettings

Description

Reads all settings (parameters, globals, and their respective values) in the given GAMS code.

Usage

readSettings(file)

Arguments

Value

A vector of parameter values and their names.

Author(s)

Mika Pflüger

See Also

readDeclarations

read_yaml_header

Description

Reads header written in yaml format from a file

Usage

read_yaml_header(file, n = 20)

Arguments

Value

A list containing the read in information

Author(s)

Jan Philipp Dietrich

Replace in File

Description

Function to replace a marked paragaph in a text file. Paragraph has to be marked in the text file with an initial "##### R SECTION START (SUBJECT) #####" and "##### R SECTION END (SUBJECT) #####" as ending. The number of # symbols can be chosen by the user, but there has to be at least one at the beginning and one at the end. Furthermore it is allowed to add further symbols at the beginning or the end of the line. "SUBJECT" is chosen by the user and is used for identification, if a text file has more than one R section.

Usage

replace_in_file(
  file,
  content,
  subject = "CODE",
  add = FALSE,
  addfile = FALSE,
  comment = "*"
)

Arguments

Author(s)

Jan Philipp Dietrich

Save Config

Description

Saves config in YAML format so that it can be read in again via loadConfig.

Usage

saveConfig(cfg, file = NULL)

Arguments

Author(s)

Jan Philipp Dietrich

See Also

loadConfig

Examples

cfg <- list(input = c(data1 = "blub.tgz", data2 = "bla.tgz"), mode = "default")
saveConfig(cfg)

selectScript

Description

Functions which allows for interactive selection of scripts/files.

Usage

selectScript(folder = ".", ending = "R")

Arguments

Value

A vector of paths to files selected by the user

Author(s)

Jan Philipp Dietrich

setScenario

Description

setScenario is adapting a given config to a predefined scenario, meaning that all settings which are fixed for the given scenario are written to the config. Settings not defined by the scenario remain unchanged.

Usage

setScenario(cfg, scenario, scenario_config = "config/scenario_config.csv")

Arguments

Value

The updated config as a config list ready for further usage.

Note

The scenario config table is a table which contains as columns the different scenarios and as rows the different settings. Empty entries for a given scenario-setting combination indicate that this setting is not defined by the scenario and should not be changed by set Scenario!

Author(s)

Jan Philipp Dietrich, Anastasis Giannousakis

See Also

check_config,getModules

settingsCheck

Description

Checks GAMS setglobals in code for consistency. Creates a warning if a setglobal command for an existing module is missing or a module is set to a realization which does not exist.

Usage

settingsCheck(path = ".", modulepath = "modules", fileName = "main.gms")

Arguments

Value

Nothing is returned.

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

Merge GAMS code into single file

Description

This function merges GAMS code which is distributed over severals files into a single GAMS file. Optionally, it also embeds R scripts into the single GAMS file

Usage

singleGAMSfile(
  modelpath = ".",
  mainfile = "main.gms",
  output = "full.gms",
  embedRScripts = FALSE
)

Arguments

Author(s)

Jan Philipp Dietrich, Anastasis Giannousakis

Examples

# copy dummymodel create single gms file out of it
file.copy(system.file("dummymodel", package = "gms"), tempdir(), recursive = TRUE)
model      <- paste0(tempdir(), "/dummymodel")
singlefile <- paste0(tempdir(), "/full.gms")
singleGAMSfile(modelpath = model, output = singlefile)

Create tgz archive from directory

Description

Creates a tgz from all files in a directory

Usage

tardir(dir = ".", tarfile = "data.tgz")

Arguments

Author(s)

Jan Philipp Dietrich

Examples

# copy dummymodel to temporary directory and compress it
file.copy(system.file("dummymodel",package="gms"),tempdir(), recursive = TRUE)
model   <- paste0(tempdir(),"/dummymodel")
archive <- paste0(tempdir(),"/dummymodel.tgz")
tardir(model,archive)

updateInterfaceMapping

Description

Function to update the mapping between interfaces and their origin modules.

Usage

updateInterfaceMapping(path = ".", modulepath = "modules")

Arguments

Author(s)

Jan Philipp Dietrich

See Also

codeCheck

update_fulldataOutput

Description

Creates GAMS code which stores automatically the levels and marginals of all equations and variables in time depending parameters.

Usage

update_fulldataOutput(
  modelpath = ".",
  modulepath = "modules",
  corepath = "core",
  loopset = "t"
)

Arguments

Author(s)

Jan Philipp Dietrich, Felicitas Beier

See Also

fulldataOutput,replace_in_file

Update Modules Embedding in GAMS code

Description

A function that updates in the GAMS code all include commands which are related to Modules. The function automatically checks which modules exist and which files in these modules exist and creates the corresponding include commands in GAMS

Usage

update_modules_embedding(
  modelpath = ".",
  modulepath = "modules/",
  includefile = "modules/include.gms",
  verbose = FALSE
)

Arguments

Note

Module phases are automatically detected checking the main code of the model, but not checking code in modules. If you want to use additional phases which are only included within a module, you need to specify them manually by adding a comment into your gams code indicating that there is an additional phase. The syntax is "* !add_phase!: <phase>", e.g. "* !add_phase!: new_phase"

Author(s)

Jan Philipp Dietrich

Examples

# copy dummymodel to temporary directory and update module embedding
file.copy(system.file("dummymodel", package="gms"), tempdir(), recursive = TRUE)
model   <- paste0(tempdir(),"/dummymodel")
update_modules_embedding(model)

writeSets

Description

Function to write a set declaration in GAMS syntax given either a a character vector or a data.frame (latter to represent a mapping set)

Usage

writeSets(sets, file = NULL)

Arguments

Value

set declaration in GAMS syntax

Author(s)

Jan Philipp Dietrich, Florian Humpenöder

Examples

countries <- c("DEU", "FRA", "ENG", "ITA", "NLD", "POL")
map <- data.frame(region = rep(c("REG1","REG2"), 3), countries = countries)
sets <- list(list(name  = "countries", 
                  desc  = "list of countries", 
                  items = countries),
             list(name = "country2region",
                  desc = "mapping between countries and regions",
                  items = map))
 cat(writeSets(sets), sep="\n")