workspace$catalogs$variantSpaces

Inventory of named variant-range sets, used to restrict a reference panel and as the default marker set for PCA and kinship (common20k). Reached as workspace$catalogs$variantSpaces.

view() and get() see the union of the read-only manifest shipped as inst/extdata/manifest.variantSpaces.csv and whatever is already cached under <workspace$config$root>/variant.space/. Rows are keyed by key + build, where key is the sanitized identity and name only a display string. add() and remove() touch the cache only; the manifest is never written.

A space that is downloadable at one build but requested at another is derived by liftover and cached under its own identity, so a repeated get() reads the cache and downloads nothing. A stored space is always the same shape: a headerless tab-separated variants.bed of chr/begin/end, chromosomes as integer codes 1-26 (X/Y/XY/MT mapped to 23/24/25/26), deduplicated and sorted.

Public methods

• VariantSpaces$new()
• VariantSpaces$view()
• VariantSpaces$get()
• VariantSpaces$add()
• VariantSpaces$remove()
• VariantSpaces$key()
• VariantSpaces$print()

Method new()

Read the variant-space manifest and build the catalog.

Usage

VariantSpaces$new(manifest.path = NULL)

Arguments

manifest.path — Character scalar path to a manifest CSV, or NULL (default). NULL reads inst/extdata/manifest.variantSpaces.csv from the installed package.

Returns

A new VariantSpaces object. Aborts when the manifest file is absent, or is missing any of the columns key, name, build, description, n.variants, url, sha256. A manifest row with an empty key gets one derived from its name.

Method view()

List every variant space that is cached locally or downloadable.

Usage

VariantSpaces$view()

Returns

A data.frame, one row per key + build, sorted by name and build, with columns key, name, build (as a display label from genomeBuilds$label()), id (cache id, NA when not cached), path, url, sha256, description, n.variants, available.local, downloadable and availability. sha256 always comes from the manifest, never from a cache row, because the stored file is the normalized table and not the .bed.gz the checksum measured. Reads the cache index; nothing is downloaded.

Method get()

Resolve one variant space, materializing it into the cache when it is not there yet.

Usage

VariantSpaces$get(
  name,
  build = NULL,
  .execute = TRUE,
  .status = polygenius.option.execution.status()
)

Arguments

name — Character scalar. Variant-space display name or internal key.

build — Character scalar build key/name, or NULL (default). NULL is only unambiguous when exactly one build of that space is available.

.execute — Logical scalar, default TRUE. When TRUE, run the producing rules — downloading or lifting over as needed — so the space is present in the cache before returning.

.status — One of "auto", "yes", "no"; default polygenius.option.execution.status(), which is "yes". Execution-status display mode for this call.

Returns

When .execute = TRUE, a named list with one element, path, the cached variants.bed. When .execute = FALSE, a ResourceSpecSet, with nothing downloaded. Aborts when name is not a single non-empty string, when the filters match several inventory rows, and when name is available in several builds or unknown entirely and build is not given.

Method add()

Register a local variant table as a cached variant space.

Usage

VariantSpaces$add(name, build, variants, overwrite = FALSE)

Arguments

name — Character scalar. Display name; resolved against the inventory first, so registering under a name already in the manifest reuses that entry's key rather than minting a second identity.

build — Character scalar build key/name.

variants — A data.frame, or a character scalar path to a file readable by data.table::fread(). The first three columns, or columns named chr/begin (or start)/end, are taken as the ranges.

overwrite — Logical scalar, default FALSE. When FALSE, an already cached key + build aborts the call.

Returns

A ResourceSpec, invisibly. Normalizes the table — chromosome codes to 1-26, invalid and duplicate ranges dropped, sorted — and writes it as <workspace$config$root>/variant.space/<id>/variants.bed with a store index entry. Aborts when name is not a single non-empty string, when variants is neither a data frame nor an existing path, when the table has fewer than three columns, or when no range survives normalization.

Method remove()

Delete cached variant spaces matching the given filters.

Usage

VariantSpaces$remove(name = NULL, build = NULL)

Arguments

name — Character scalar display name or key, or NULL (default) to match any name.

build — Character scalar build key/name, or NULL (default) to match any build. An unrecognized build string aborts.

Returns

NULL, invisibly. Deletes each matching resource directory under <workspace$config$root>/variant.space/ and its store index rows, and reports the count. Called with no arguments it removes every cached variant space. The manifest is untouched, so a removed downloadable space still appears in view() and get() re-downloads it.

Method key()

Resolve a variant-space display name to its internal key.

Usage

VariantSpaces$key(name, build = NULL)

Arguments

name — Character scalar. Display name or internal key.

build — Character scalar build key/name, or NULL (default) to match any build.

Returns

Character scalar internal key. Aborts when nothing in the inventory matches.

Method print()

Print the variant-space inventory, one line per entry, marking cached entries against downloadable ones.

Usage

VariantSpaces$print(...)

Arguments

... — Unused. Present for print-method compatibility.

Returns

self, invisibly.

Other catalogs: GenomeBuilds, LDblocks, LDs, LiftoverChains, ReferencePanels, workspace_catalogs