Contents

workspace$config

Read and change PolyGenius workspace settings

The runtime settings every generate, compute, associate, evaluate and visualize call resolves against. Each setting is a read-only field on workspace$config; workspace$config$update() is the only way to change one, and workspace$config$as.list() takes a plain-list snapshot of all of them.

Usage

workspace$config$update(
  root = NULL,
  max.cores = NULL,
  max.memory = NULL,
  max.model.column.bytes = NULL,
  max.absorb.batch.models = NULL,
  oversubscribe = NULL,
  verbosity = NULL,
  execution.status = NULL,
  execution.log.propagate = NULL,
  palette = NULL,
  dashboard.live = NULL,
  downloads.base = NULL
)

workspace$config$as.list()

S3 method for class 'PolyGeniusConfig'

print(x, ...)

Arguments

Argument	Description
`root`	Character scalar path, or NULL (default) to leave it unchanged. Workspace cache and output root, under which every cached resource lives; it is expanded and normalized and need not exist yet. Ships as tools::R_user_dir("PolyGenius", "cache").
`max.cores`	Positive integer, Inf, or NULL (default) to leave it unchanged. Cap on engine worker count; ships as NULL, and both NULL and Inf resolve to detected cores minus one.
`max.memory`	Positive numeric scalar in GiB, Inf, or NULL (default) to leave it unchanged. Engine memory budget; ships as Inf, which disables the check. A value strictly between 0 and 1 aborts as an almost-certain unit error (bytes or MB).
`max.model.column.bytes`	Positive numeric scalar in bytes, Inf, or NULL (default) to leave it unchanged. Byte budget on the column(s) a single mutate.variants() call materializes; ships as 4L * 1024L^3 (4 GiB), and Inf disables the check.
`max.absorb.batch.models`	Positive integer, Inf, or NULL (default) to leave it unchanged. How many models generate$models() folds into one PolyGeniusBackbone$absorb() call before flushing; ships as 50L. Inf removes batching's memory bound, leaving every model of one build resident at once.
`oversubscribe`	Logical scalar, or NULL (default) to leave it unchanged. When TRUE, an explicit finite max.cores is honored above the detected-core cap; ships as FALSE.
`verbosity`	One of "fatal", "error", "warn", "info", "debug", "trace", "all", "off", or NULL (default) to leave it unchanged. Console logger threshold; ships as "info".
`execution.status`	One of "auto", "yes", "no", or NULL (default) to leave it unchanged. Status display mode for execution runs; ships as "yes", and "auto" shows the display only while the console logger is off.
`execution.log.propagate`	One of "yes", "no", or NULL (default) to leave it unchanged. Whether execution logs propagate to the parent logger; ships as "no".
`palette`	One of "polygenius", "nature-npg", or NULL (default) to leave it unchanged. Palette system every visualize function draws with by default; ships as "polygenius", and a per-plot palette argument overrides it.
`dashboard.live`	One of "auto", "yes", "no", or NULL (default) to leave it unchanged. Whether to auto-host a live execution dashboard; ships as "auto".
`downloads.base`	Character scalar http:// or https:// base URL, or NULL (default) to leave it unchanged. Where PolyGenius fetches its own downloadable assets from -- reference panels, liftover chains, LD blocks, variant spaces and the PLINK2 binary. Ships as https://polygenius.holstegelab.eu/downloads, overridable at session start by the POLYGENIUS_DOWNLOADS_BASE environment variable. Point it at an HTTP mirror of that tree when the default host is unreachable; a filesystem path is not accepted, so an air-gapped machine needs a local HTTP server rather than a directory. The mirror must be a byte-exact copy: only the PLINK archive is checksum-verified today, so wrong bytes from any other family would be cached under the canonical identity. Only PolyGenius's own URLs are redirected -- PGS Catalog, GWAS Catalog, OpenGWAS and GCTB are unaffected -- and the redirect does not change any resource's cache identity. A malformed POLYGENIUS_DOWNLOADS_BASE is rejected while the workspace is being built, which makes library(PolyGenius) itself fail with the offending value named.

Value

update(): the PolyGeniusConfig object, invisibly. Called for its side effect of changing the settings of the running session, and of rebuilding the execution internals when an infrastructure setting changes.
as.list(): a plain named list of the twelve settings — root, max.cores, max.memory, max.model.column.bytes, max.absorb.batch.models, oversubscribe, verbosity, execution.status, execution.log.propagate, palette, dashboard.live, downloads.base — as of the moment of the call. Reads only; the derived log.dir and execution.dir are not included.

Details

update() validates every supplied value before changing anything, so a rejected value leaves the config exactly as it was. An argument left at NULL keeps its current value, which also means a setting cannot be returned to its shipped value by passing NULL. An update whose proposed settings equal the current ones does nothing at all.

Changing an infrastructure setting — root, max.cores, max.memory, oversubscribe, verbosity, execution.status or execution.log.propagate — tears down and rebuilds the execution internals, so in-flight engine state is discarded. The remaining settings are read by later calls without a rebuild.

log.dir and execution.dir are derived from root on read, as file.path(root, "logs") and file.path(root, "execution"). They are readable fields but not settings, and update() has no argument for either.

Examples

# Read the settings, individually or as a snapshot
workspace$config$verbosity
settings <- workspace$config$as.list()
settings$max.memory

# Change one and put it back; palette is cosmetic, so no engine rebuild
workspace$config$update(palette = "nature-npg")
workspace$config$palette
workspace$config$update(palette = settings$palette)


```r

# Infrastructure settings; each rebuilds the execution internals
workspace$config$update(root = "~/polygenius-cache", max.cores = 8, max.memory = 32)