Contents

generate$models

Build models from source and algorithm specifications

generate$models() cross-joins one or more source specifications with one or more algorithm specifications, then resolves the requested models through the execution engine. Every source is fitted with every algorithm.

Usage

generate$models(
  sources = NULL,
  algorithms = NULL,
  target.build = NULL,
  naming = "auto",
  .execute = TRUE
)

Arguments

Argument	Description
`sources`	A ResourceSpecSet, a ResourceSpec, or a list of either, default NULL. GWAS sources, typically from generate$sources$...(). Every entry must be a gwas.sumstats spec; NULL or an empty set aborts.
`algorithms`	A ResourceSpecSet, a ResourceSpec, or a list of either, default NULL. Algorithms, typically from generate$algorithms$...() and combined with c(). Every entry must be a generate.algorithm spec; NULL or an empty set aborts.
`target.build`	Character scalar or NULL (default). Genome build the returned set is lifted to. Model resources are always generated and cached in their native build first, and the lift happens afterwards.
`naming`	One of "auto" (default), "trait", "algorithm", "tuning", "verbose". How to name the returned models; each name carries only the dimensions that distinguish it from its siblings. "auto" — Set-aware: includes the GWAS trait only when more than one GWAS is present, the algorithm unless a single algorithm is fully implied by the GWAS, and only the tuning parameters that vary within an algorithm. Escalates to the GWAS id then source if names would otherwise collide. "trait" — The GWAS trait, falling back to id, then source. "algorithm" — The algorithm name only. "tuning" — Algorithm plus its tuning parameters, e.g. LDpred2 (h2=3e-01, p=1e-03). "verbose" — Trait, id, algorithm, and tuning parameters. Numeric parameters render in compact scientific notation. Any residual duplicate names get a (#k) suffix.
`.execute`	Logical scalar, default TRUE. TRUE runs the execution engine and returns resolved models; FALSE returns the requested specifications without scheduling anything.

Value

When .execute = TRUE, a PGSLibrary holding every model that generated successfully, carrying the provenance record above under provenance(). A model that failed is listed in provenance(set)$misc$failed.models and warned about rather than being fatal to the rest; when no model at all resolved, the call aborts instead of returning an empty set. When .execute = FALSE, a ResourceSpecSet of unresolved polygenius.model specifications.

Generated models are written to the workspace resource cache, and the run's execution stream, log and summary are persisted at the paths recorded in provenance(). A returned set spanning several genome builds carries no multi-build advisory, because the batched collection path does not go through PGSLibrary(); pass target.build to converge it.

Details

Source specs are gwas.sumstats requests whose genome build may still be unknown at request time; the source rule materialises it during execution, and model rules bind build-matched reference-panel, LD and clumping resources from the resolved build.

Some algorithms expand during execution. LDpred2-grid and lassosum2 each run once per source/algorithm family and then emit one completed PGS per returned candidate effect vector. Candidate values such as LDpred2 grid h2/p/sparse or lassosum2 lambda/delta become part of each final model's resource identity.

Provenance of the returned set

provenance(set) returns how the set was made: name = "generate$models", the deparsed call, the arguments supplied in params, and a stamped created/version. What the request resolved to is in misc -- the sources and algorithms requested, target.build and naming; plus the run outcome: failed.models, execution.status, the persisted execution.jsonl.path / execution.log.path / execution.summary.path, and execution.wall.seconds. The full contract, shared with the PGS import paths, is in the Library-level provenance section of PGSLibrary.

A set produced from this one by a grammar verb -- models$filter.models(...) -- keeps this record verbatim. A verb narrows a library; it does not make one, so the record still names the call that did, and the run handles still resolve it (visualize$execution$performance() works on a narrowed set).

Examples

models <- generate$models(
  sources    = generate$sources$opengwas("ieu-b-2"),
  algorithms = generate$algorithms$ClumpingThresholding(
    pval = c(5e-8, 1e-5), reference.panel = "EUR"
  ),
  naming     = "tuning"
)

# Inspect the requested resources without scheduling anything
specs <- generate$models(
  sources    = generate$sources$opengwas("ieu-b-2"),
  algorithms = generate$algorithms$lassosum2(reference.panel = "EUR"),
  .execute   = FALSE
)

Aliases: generate-models, generate$models