Package 'lucode2'

Description

Add EOF text to all files in the code in order to ease debugging

Usage

addEOF(path = ".", filetypes = c("inc", "prn", "gms"))

Arguments

Author(s)

Anastasis Giannousakis

See Also

removeEOF

Examples

## Not run: 
addEOF()

## End(Not run)

Description

This function adds a standard Github action workflow called "check.yaml" to the project which runs lucode2::check(), checks the validation key, and creates a coverage report using codecov. This file is overwritten automatically each time this function is run and should not be edited by hand. Additional Github actions can be added as separate files.

Usage

addGitHubActions(lib = ".")

Arguments

Details

In addition, this function adds a codecov.yml to the repository, if not already existing. This file is only created if missing and can be edited manually.

Author(s)

Jan Philipp Dietrich

See Also

buildLibrary

Examples

## Not run: 
addGitHubActions()

## End(Not run)

Description

Apply auto-formatting using styler::style_file to the given files. Does not change indentation.

Usage

autoFormat(
  files = getFilesToLint(),
  ignoreLintFreeFiles = TRUE,
  lintAfterwards = TRUE
)

Arguments

Author(s)

Pascal Sauer

See Also

getFilesToLint

Examples

## Not run: 
lucode2::autoFormat()

## End(Not run)

Description

Builds R libraries. Includes checks for consistency. Find solutions to common problems at https://github.com/pik-piam/discussions/discussions/18

Usage

buildLibrary(
  lib = ".",
  cran = TRUE,
  updateType = NULL,
  updateLucode2 = TRUE,
  autoCheckRepoUpToDate = TRUE
)

Arguments

Details

This function is designed to help building and checking R libraries. It performs the following steps:

• Version: Determination of a new version number (Can also be defined by the user).

• Date: Determination of a the date of the build (Can also be defined by the user).

• Linter: Check for code style problems.

• R check: Check whether the library is consistent and can be built.

• Package building: Builds the .zip and .tar.gz packages under windows. Under linux, only the .tar.gz package is built.

Note

The behavior of buildLibrary can be configured via the .buildLibrary file in the main folder of the package. It uses YAML format and can contain the following entries:

• ValidationKey: This entry always exists and is written automatically by buildLibrary It confirms that the package has been successfully build via the function.

• AutocreateReadme (optional): yes/no - decides whether buildLibrary automatically updates the README.md file or not (default: yes)

• AddInReadme (optional): Additional entries to be added to the autocreated README. Provided either in markdown format or as paths to RMarkdown (Rmd) or Markdown (md) files

• AddLogoReadme (optional): Additional logo to be added to the autocreated README. Provided as path to logo in PNG format

• LogoHeightReadme (optional): Height of the logo in README in px

• AcceptedWarnings (optional): a list of Warnings which should be ignored by buildLibrary (autocompletion via asterisks allowed)

• AcceptedNotes (optional): a list of Notes which should be ignored by buildLibrary (autocompletion via asterisks allowed)

• allowLinterWarnings: yes/no - If set to "no" linter warnings will stop the build process. (default: yes)

• enforceVersionUpdate: yes/no - If set to "yes", the version number must be incremented to a non-dev version number for the build process to succeed. (default: no)

• skipCoverage: yes/no - If set to "yes", running code coverage using covr as part of the GitHub workflow will be skipped. (default: no)

Author(s)

Jan Philipp Dietrich, Anastasis Giannousakis, Markus Bonsch, Pascal Sauer

See Also

package2readme, lint, autoFormat

Examples

## Not run: 
buildLibrary()

## End(Not run)

Description

Builds documentation and runs checks, tests, and linter. Find solutions to common problems at https://github.com/pik-piam/discussions/discussions/18

Usage

check(
  lib = ".",
  cran = TRUE,
  config = loadBuildLibraryConfig(lib),
  runLinter = TRUE
)

Arguments

Details

This function builds documentation including vignettes via devtools::document(). It runs devtools::check() (without tests), then in a separate clean R session it runs devtools::test(), and finally lucode2::lint(). Before linting ".lintr" config files are created if missing. The actual linter rules are defined in lintrRules. In general undesirable functions and operators result in linter warnings, but not in the tests and vignettes subdirectories. Warnings and notes in checks and tests are only allowed if the given config defines them as accepted, otherwise this function will stop.

Author(s)

Jan Philipp Dietrich, Pascal Sauer

See Also

buildLibrary, lint, lintrRules

check, test

Examples

## Not run: 
lucode2::check()

## End(Not run)

Description

Checks if there are CRAN-packages with the same name as those in our PIK-CRAN whose version is newer

Usage

check_versions(mail = TRUE, test = FALSE, gitpath = NULL)

Arguments

Author(s)

Anastasis Giannousakis

Description

Checks whether the local repo is up-to-date with the remote tracking branch and the default branch of the upstream remote. Will throw an error if not up-to-date and prints a git command to update.

Usage

checkRepoUpToDate(pathToRepo = ".", autoCheckRepoUpToDate = TRUE)

Arguments

Author(s)

Pascal Sauer

Description

Check if one or more packages are available and try to install the missing packages. Throw an error if at least one of the required packages is still missing after the installation attempt.

Usage

checkRequiredPackages(
  requiredPackages,
  requiredFor = "",
  installFunction = install.packages,
  readlineFunction = readline,
  libPaths = .libPaths()
)

Arguments

Author(s)

Pascal Sauer

See Also

requireNamespace

Examples

## Not run: 
checkRequiredPackages(c("ggplot2", "lusweave"), "lucode2::readRuntime(..., plot = TRUE)")

## End(Not run)

Description

Checks the current R setup for common problems and reports info such as OS and R version.

Usage

checkup()

Value

Invisibly, the report as a list.

Author(s)

Pascal Sauer

Description

Copy a file from lucode2 into the current package.

Usage

conditionalCopy(relativePath, nameInInstExtdata = basename(relativePath))

Arguments

Details

For normal packages, it will simply overwrite the given file from the corresponding file in lucode2's extdata. For lucode2 itself, it instead checks if the file in extdata matches the file in the main folder. If not, it asks if the file in extdata should be updated.

Description

An extended print command which formats information in a way that it is good to use for a log-file

Usage

eprint(var_name, envir = parent.frame())

Arguments

Author(s)

Jan Philipp Dietrich, Oliver Richters

See Also

eprint_list

Examples

## Not run: 
a <- 1:3
eprint("a")

## End(Not run)

### print additional information concerning loaded configuration###
### ePrint (extended Print) offers an extended output functionality which
### allows to create easily log-files with all relevant information

Description

Same as eprint, but expecting a vector with variable names

Usage

eprint_list(var_list, envir = parent.frame())

Arguments

Author(s)

Jan Philipp Dietrich

See Also

eprint

Examples

a <- 1:3
b <- "blub"
lucode2:::eprint_list(c("a", "b"))

Description

Extracts the value (right-hand-side) of a string of the structure "name=value" and converts it to an appropriate format. This file also reads arguments from command line. To use this script you have to include it by typing source("readArgs.R") in your script and call readArgs(allowed_args) including all arguments that can be read from command line.

Usage

extract_arguments(inputArg)

Arguments

Value

Author(s)

Jan Philipp Dietrich

See Also

readArgs

Examples

## Not run: 
extract_arguments("bla=1:9")
# [1] 1 2 3 4 5 6 7 8 9

extract_arguments("blub=3,5,7")
# [1] 3 5 7

extract_arguments("ble=hallo")
# [1] "hallo"

## End(Not run)

Description

Extracts scenario names from coupled runs in the given outputfolder. The scenario names will be extracted based on the folder names of the results folders.

Usage

findCoupledruns(resultsfolder)

Arguments

Value

A vector containing the names of the scenarios.

Author(s)

David Klein

Description

Find all dependencies of an R project.

Usage

findDeps(devDeps = TRUE)

Arguments

Details

This is a wrapper around 'renv::dependencies()' that does not report dependencies on core R packages, because these are always available.

Value

A dataframe documenting which dependency is needed where.

Author(s)

Pascal Sauer

See Also

dependencies

Description

Collects paths to all coupled runs (iterations) in modelpath that contain runname. For each entry in runname the paths are sorted by the modification time of the respective fulldata.gdx

Usage

findIterations(runname, modelpath = ".", latest = FALSE)

Arguments

Value

A vector containing the paths to the iterations of coupled runs.

Author(s)

David Klein

Description

Fix merge conflicts in files auto-edited by buildLibrary (.buildlibrary, .zenodo.json, DESCRIPTION, README.md).

Usage

fixBuildLibraryMergeConflict(lib = ".")

Arguments

Details

The ValidationKey in .buildlibrary will be set to an empty string and the higher version number in DESCRIPTION is used. buildLibrary needs to be run after this function to deal with the ValidationKey and the merge markers in .zenodo and README.md.

Description

Fix file format of text files (e.g. line/file endings).

Usage

fixfile(f)

Arguments

Author(s)

Jan Philipp Dietrich

Description

used to quickly read in the default values of a function

Usage

functionHeaderDefaults(...)

Arguments

Value

no direct return, values are assigned to .GlobalEnv

Author(s)

Benjamin Leon Bodirsky

Examples

## Not run: 
test <- function(a = "klk", b = "kjlkv", kk = 3) {
paste(a, b, kk)
}
functionHeaderDefaults(a = "klk", b = "kjlkv", kk = 3)
print(a)
paste(a, b, kk)

## End(Not run)

Description

Returns information about cluster load in case that the command "sclass" is available. Otherwise, it returns NULL

Usage

getClusterLoad()

Value

NULL, if command "sclass" is not available, otherwise returns a named vector with current load on available partitions

Author(s)

Jan Philipp Dietrich

Description

Get the R files the current git user is responsible for to pass them to the auto-formatter and/or linter.

Usage

getFilesToLint(pathToGitRepo = ".")

Arguments

Details

The files of interest are identified using git via system() (and shell() for windows). All currently untracked files and changed files (both staged and unstaged) are collected, as well as files that were changed in non-merge commits authored by the current git user since the last version commit (a commit where .buildLibrary was changed, presumably to increase the version number). Of those the absolute paths to .R, .Rmd and .Rnw files are returned as a character vector.

Author(s)

Pascal Sauer

See Also

lint, autoFormat

Examples

lucode2:::getFilesToLint()

Description

Creates a suggestion for an Authors entry for the DESCRIPTION of a package. Suggestion is based on author information in roxygen headers and authors are ranked based on number of mentionings.

Usage

getPackageAuthors(folder = "R")

Arguments

Details

Please be aware that the output will most likely require some manual processing before it can be used in the DESCRIPTION!

Author(s)

Jan Philipp Dietrich

Description

Get the scenario names (titles) of runs from the specified output folder(s).

Usage

getScenNames(dirs)

Arguments

Value

A vector containing the titles used as scenario names for e.g. plots

Author(s)

Lavinia Baumstark

Description

Print each git author's first name, last name, and mail address in a way that could be copy pasted into DESCRIPTION. Please note that this list usually still needs to be carefully checked e.g. for duplicates and cleaned.

Usage

gitAuthors()

Value

Invisibly, a data.frame with the following columns: raw, firstName, lastName, mailAdress.

Author(s)

Pascal Sauer

Description

Increment a version number at the specified position.

Usage

incrementVersion(currentVersion, position, defLengths = 3)

Arguments

Value

The new version string.

Author(s)

Jan Philipp Dietrich, Anastasis Giannousakis, Markus Bonsch, Pascal Sauer

See Also

buildLibrary

Examples

lucode2:::incrementVersion("1.23.45", 3)

Description

Checks if the version number in the DESCRIPTION file of a given package has been updated (may not be a version number for development stage packages).

Usage

isVersionUpdated(
  repo = "https://rse.pik-potsdam.de/r/packages/",
  config = loadBuildLibraryConfig()
)

Arguments

Author(s)

Falk Benke

Description

Check the given files for linter warnings using lintr::lint.

Usage

lint(files = getFilesToLint())

Arguments

Details

For files in the vignettes and tests folder less strict rules are applied, e.g. using ::: usually leads to a linter warning, but not in vignettes/tests. Which linter rules are used depends on ".lintr" config files. check creates lintr config files that use lintrRules.

Value

A named list, where the names are the paths to the linted files and the values are lists containing the linter warnings.

Author(s)

Pascal Sauer

See Also

getFilesToLint, lintrRules, autoFormat, lint

Examples

## Not run: 
lucode2::lint()

## End(Not run)

Description

This function defines the rules to be used by the linter called lintr. check creates ".lintr" config files that use this function.

Usage

lintrRules(allowUndesirable = FALSE, modification = list())

Arguments

Details

To change which linters are applied for a package edit the .lintr file to use the modification argument, see example.

Value

A named list mapping linter names to linter functions.

See Also

check, lint

Examples

## Not run: 
lintr::lint_dir(linters = lucode2::lintrRules())

# return usual linters with a different object_name_linter and without the todo_comment_linter
snakeCaseLinter <- lintr::object_name_linter(styles = "snake_case")
lucode2::lintrRules(modification = list(object_name_linter = snakeCaseLinter,
                                        todo_comment_linter = NULL))

## End(Not run)

Description

Load the build configuration from .buildLibrary. If the file does not exist it is created.

Usage

loadBuildLibraryConfig(lib = ".")

Arguments

Value

The configuration loaded from .buildLibrary as a list.

Author(s)

Jan Philipp Dietrich, Pascal Sauer

See Also

buildLibrary

Description

Function to set configuration parameters in configuration files (e.g. default.cfg and magpie.gms). This replacement is useful, when using R to manage different model runs at once. Please check your results after replacement!

Usage

manipulateConfig(configFile, ...)

Arguments

Author(s)

Jan Philipp Dietrich, Markus Bonsch, David Klein

See Also

manipulateFile

Examples

## Not run: 
manipulateConfig("config/default.cfg", input = "test_new_yields", title = "yihaa", revision = 4.2)
manipulateConfig("magpie.gms", s_max_timesteps = 4, s_use_gdx = -1)

## End(Not run)

Description

Function to replace a specific text string in a text file. Useful to manipulate GAMS sourcecode files.

Usage

manipulateFile(file, manipulations, perl = TRUE, ...)

Arguments

Author(s)

Jan Philipp Dietrich

See Also

manipulateConfig

Examples

# manipulateFile("example.txt",list(c("bla","blub"),c("a","b")))

Description

Function checks memory usage and shows the biggest objects in the given environment

Usage

memCheck(
  order.by = "Size",
  decreasing = TRUE,
  n = NULL,
  envir = parent.frame(),
  gc = TRUE
)

Arguments

Details

This function is based on an idea posted at stack overflow: http://stackoverflow.com/questions/1358003/tricks-to-manage-the-available-memory-in-an-r-session

Author(s)

Jan Philipp Dietrich

Examples

## Not run: 
memCheck()

## End(Not run)

Description

Support function to merge run statistics which have been derived with runstatistics

Usage

mergestatistics(
  dir = ".",
  file = NULL,
  renew = FALSE,
  quickcheck = FALSE,
  pattern = "*\\.[rR]da",
  removeCols = NULL,
  keepCols = NULL
)

Arguments

Value

A data table containing the merged run statistics or NULL in case the data was not recalculated

Author(s)

Jan Philipp Dietrich

Description

Creates a README.md for a R package.

Usage

package2readme(package = ".", add = NULL, logo = NULL, logoHeight = NULL)

Arguments

Author(s)

Jan Philipp Dietrich

Examples

package2readme("lucode2")

Description

Function to print version number and time since last update formatted to standard output. Considers CRAN, the RSE server, and r-universe.

Usage

packageInfo(
  package,
  repos = c("https://cran.rstudio.com/", "https://rse.pik-potsdam.de/r/packages/",
    "https://pik-piam.r-universe.dev")
)

Arguments

Author(s)

Jan Philipp Dietrich

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

Description

Fetches the names of packages available on https://pik-piam.r-universe.dev/ui#builds

Usage

piamPackages()

Value

A character vector of names of packages available on https://pik-piam.r-universe.dev/ui#builds

Description

For coupled runs: Searches the output folder for all existing run folders, checks which of them are currently running on the cluster, ignores them, checks for the remaining runs whether there is a reporting. Produces the reporting if it is missing. #'

Usage

produce_missing_reports(modeldir = "./")

Arguments

Author(s)

David Klein

Description

Function reads arguments from command line of the structure value=content and transforms them to R-Values, if they are called as allowed arguments.

Usage

readArgs(
  ...,
  .argv = commandArgs(trailingOnly = TRUE),
  .envir = parent.frame(),
  .flags = NULL,
  .silent = FALSE
)

Arguments

Value

vector of activated flags, if any

Author(s)

Jan Philipp Dietrich, Oliver Richters

See Also

manipulateConfig

Examples

# Create an R-file "test.R" with following code:
value1 <- "old"
value2 <- 2
value3 <- "willstaythesame"
flags <- readArgs("value1", "value2", "value4", .flags = c(t = "--test", p = "--parallel"))
message(value1)
message(value2)
message(value3)
if ("--test" %in% flags) {
  message("You are in test mode")
}
if ("--parallel" %in% flags) {
  message("You are in parallel mode")
}

# Open the command line and execute the following code:
# Rscript test.R -t --parallel value1=new value2=3 value3=isnotallowed

# Output:
#
# ### READ COMMAND LINE - ASSIGNED CONFIGURATION ###
# value1 <- new
# value2 <- 3
# value4 not defined
# Flags: --parallel, --test
# ### READ COMMAND LINE - CONFIGURATION END ###
#
# new
# 3
# willstaythesame
# You are in test mode
# You are in parallel mode


### function that reads all allowed arguments from command line ###

Description

Reads all runtime information from given experiments. The runtime is given in hours and is the runtime of GAMS.

Usage

readRuntime(path, plot = FALSE, types = NULL, coupled = FALSE, outfname = NULL)

Arguments

Value

A data frame containing the run names and runtime information in hours.

Author(s)

David Klein

Description

remove EOF text from all files in the code

Usage

removeEOF(path = ".", filetypes = c("inc", "prn", "gms"))

Arguments

Author(s)

Anastasis Giannousakis

See Also

addEOF

Examples

## Not run: 
removeEOF()

## End(Not run)

Description

Use this function to change the name of a run after it has finished. This function renames the run folder, change the run title in the cfg and in the reporting. This can be useful if the initial name of a run was not meaningful. However, inconsistencies will remain, since the function will NOT rename the scenario in the list file, the gdx, and the results database.

Usage

rename_scenario(map, keep_time_stamp = FALSE)

Arguments

Author(s)

David Klein

Description

Removes all objects except specified ones from the workspace

Usage

rmAllbut(..., list = character(), clean = TRUE)

Arguments

Details

Helps to clean the workspace. Only objects specified in ... survive. Specify clean =TRUE to really free the memory.

Author(s)

Markus Bonsch

See Also

rm,ls

Examples

# Create some objects
a <- 1
b <- 2
c <- 3
# show them
ls()
# delete all but b and c
rmAllbut(b, c)
ls()
# delete all but b
test <- "b"
rmAllbut(list = test)
ls()

Description

Support function to collect run statistics.

Usage

runstatistics(file = "runstatistics.Rda", overwrite = TRUE, submit = NULL, ...)

Arguments

Value

An invisible list containing run statistics as stored in the given file

Author(s)

Jan Philipp Dietrich

Examples

f <- tempfile()
 runstatistics(file = f, user = Sys.info()[["user"]])
 print(runstatistics(file = f))
 runstatistics(file = f, submit = tempdir())

Description

A function that sends an automatic email with each push to a gitlab repo

Usage

sendmail(
  path = NULL,
  gitrepo,
  file,
  commitmessage,
  remote = FALSE,
  reset = FALSE
)

Arguments

Author(s)

Anastasis Giannousakis

Description

Returns a list with information about the current session (session info, used library paths and installed libraries)

Usage

setup_info()

Value

A list with information about the current session and the currently used R setup.

Author(s)

Jan Philipp Dietrich

Examples

setup_info()

Description

Mini function that allows you to set a directory based on a readline input. Very useful for Windows users, as it replaces backslashes by slashes.

Usage

setwd2(return_only = FALSE)

Arguments

Value

if return_only=FALSE: Nothing, but the working directory is set to. Otherwise: no working directory returned, but path transformed.

Author(s)

Benjamin Leon Bodirsky

Description

Convenience function to rename variables in an R file from snake to camel case.

Usage

snakeToCamel(pathToFile, ask = TRUE)

Arguments

Description

Checks whether a system command is available (does not return an error), or not

Usage

SystemCommandAvailable(command)

Arguments

Value

Boolean indicating whether the command is available, or not

Author(s)

Jan Philipp Dietrich

Examples

SystemCommandAvailable("ls")

Description

Installs a package in a temporary library and loads that library on top of the existing one

Usage

testPackage(repo, tmpLib = tempdir(), ...)

Arguments

Author(s)

Jan Philipp Dietrich

Examples

## Not run: 
testPackage("[email protected]:pik-piam/lucode2")

## End(Not run)

Description

Function to update an package repository. Run this function on a folder which contains packages sources as subfolders. Packages should be managed via git in order to be updated properly. To add a new package to the repo just checkout/clone it into this folder. The function will automatically detect the new package and add it.

Usage

updateRepo(
  path = ".",
  check = TRUE,
  forceRebuild = FALSE,
  clean = TRUE,
  skipFolders = "Archive",
  repoUrl = "https://rse.pik-potsdam.de/r/packages"
)

Arguments

Author(s)

Jan Philipp Dietrich, Pascal Sauer

See Also

buildLibrary

Description

Support function which creates a key out of a version date combination

Usage

validationkey(version, date)

Arguments

Details

This function is used in buildLibrary to offer the package publication server an option to check whether the package has been properly and successfully (no errors/warnings/notes) checked before its commit.

The calculated key is not safe and can easily be reproduced, but should be complicated enough to encourage users running the buildLibrary check properly.

Author(s)

Jan Philipp Dietrich

See Also

buildLibrary

Description

Support function which validates a key out of a version date combination

Usage

validkey(package = ".", stopIfInvalid = FALSE)

Arguments

Details

This function is used to check whether buildLibrary has been run properly and without problems or not

Value

list with version, date and result of validation test

Author(s)

Jan Philipp Dietrich

See Also

buildLibrary

Description

Run R CMD check completely without stopping. Then stop on errors, or unaccepted warnings and notes.

Usage

verifyCheck(cran, acceptedWarnings, acceptedNotes)

Arguments

Author(s)

Pascal Sauer

Description

Run linter and stop on linter warning unless linter warnings are allowed.

Usage

verifyLinter(allowLinterWarnings = FALSE)

Arguments

Author(s)

Pascal Sauer

Description

Run tests and stop on error or unaccepted warning.

Usage

verifyTests(acceptedWarnings)

Arguments

Author(s)

Pascal Sauer