Contents

compute$scores.plan

Estimate the resources a scoring run will need

Predicts the peak RAM, batch count and scoring strategy compute$scores() would use for a workload, and reports what a given memory value resolves to. Never runs PLINK, never reads genotypes, and never returns a score matrix.

Usage

compute$scores.plan(
  study,
  maf.thr = 0,
  model.filter = function(variants) rep(TRUE, nrow(variants)),
  models = NULL,
  memory = NULL,
  exact = TRUE,
  sweep = NULL
)

Arguments

Argument	Description
`study`	A PolyGeniusStudy. One with no model library attached is fine as long as models supplies them; the call aborts only when neither does.
`maf.thr`	Numeric scalar in [0, 0.5], default 0. Any value above 0 forfeits the fused path in the estimate, exactly as in [compute$scores()](/reference/compute-scores/).
`model.filter`	Function of one argument, default function(variants) rep(TRUE, nrow(variants)). Same return contract as [compute$scores()](/reference/compute-scores/)'s own model.filter; the mask is pushed down, so a filtered plan measures the filtered variant union rather than the unfiltered one. The reported strategy does not account for a supplied filter disabling the file-backed regime, so it can read "file.backed" where a real scoring run would take the in-memory backbone path.
`models`	A PGS, a PGSLibrary, a variant data.frame, a named list of variant data.frames, a list of PGS objects, or omitted (the default). Explicit models to plan for instead of the ones attached to study; omitting it plans for every attached model. Supplying it as NULL aborts, and model names resolve, exactly as in [compute$scores()](/reference/compute-scores/).
`memory`	Positive numeric scalar (GiB), a named list, or NULL (default). Resolved into the same three knobs a real scoring call would use; NULL falls back to workspace$config$max.memory. See [compute$scores()](/reference/compute-scores/)'s Memory and batching section. Ignored when sweep is supplied, which resolves a candidate per row instead.
`exact`	Logical scalar, default TRUE. TRUE computes the exact scored union with one streaming pass over the models; FALSE uses the dense upper bound n.variants.union = n.variants.total. Any non-logical or NA value aborts.
`sweep`	A numeric vector of GiB scalars, a list mixing bare numeric scalars with named-list memory-shaped overrides, or NULL (default, a single estimate). Each candidate is resolved and estimated independently against the same workload dimensions, measured once rather than once per candidate. Anything neither numeric nor a list aborts.

Value

When sweep is NULL (the default), a named list: peak.ram.bytes, peak.ram.mb, n.batches, n.groups, strategy ("fused", "via.extract" or "file.backed"), n.models, n.variants.union, n.variants.total, n.samples, the cost model's breakdown terms (est.score.cells, est.bytes.per.cell, est.input.bytes, est.records.peak.bytes, est.union.bytes, est.file.bytes, est.genotype.read.passes), and memory — itself a list of requested (the argument as given, possibly NULL), resolved (cells, plink.memory, file.backed.threshold) and source (one of "literal", "derived" or "supplied" per knob).

When sweep is supplied, a data.table with one row per candidate and columns label (the candidate stringified), strategy, n.batches, peak.ram.mb, cells, plink.memory (NA_real_ when PLINK is left uncapped) and file.backed.threshold.

Details

The workload dimensions — model count, sample count, genotype file count, format and the scored variant union — are measured once, then fed to the same cost model and the same memory resolution a real scoring call uses. exact = TRUE folds the true scored union in one streaming pass over the models; exact = FALSE substitutes the dense upper bound n.variants.union = n.variants.total, which assumes no variant is shared between any two models and is only a first-glance sanity check.

No wall-clock estimate is reported in either shape: the cost model is fitted against measured peak memory and carries no time coefficient. Use n.batches, and on the single-estimate shape est.genotype.read.passes, as the time-correlated proxies.

Examples

plan <- compute$scores.plan(data)
plan$strategy
plan$peak.ram.mb

# What would 4, 8 or 16 GiB buy?
compute$scores.plan(data, sweep = c(4, 8, 16))