Skip to contents

Unified ancestry backend plugins and execution

ancestry_backends.Rd

Defines the backend-neutral plugin contract and unified ancestry execution API. Built-in adapters are supplied for ADMIXTURE, fastStructure, and LEA sNMF. Optional tools are discovered at runtime and unavailable backends can be skipped transparently.

Usage

new_ancestry_backend(name, availability, execute, parse = identity,
  validate = function(task) invisible(task), description = "", version = "1.0")

new_ancestry_backend_registry(backends = list())

register_ancestry_backend(registry, backend, overwrite = FALSE)

ancestry_backend_status(registry = default_ancestry_backend_registry())

default_ancestry_backend_registry()

run_ancestry(input, sample_ids, backend = "auto", k_values = 2:10,
  replicates = 5L, seed = 42L,
  registry = default_ancestry_backend_registry(), fail_if_none = TRUE)

Arguments

name

Stable lowercase backend identifier.

availability

Function returning a logical value or a list with available and reason.

execute

Function accepting one scheduled task and returning a backend-native result.

parse

Function converting a native result and task to a PopgenVCFAncestryReplicate.

validate

Optional backend-specific task validator.

description

Human-readable backend description.

version

Backend plugin contract version.

backends

List of backend specifications.

registry

A PopgenVCFAncestryBackendRegistry.

backend

Backend specification when registering; backend name, names, "auto", or "all" when running.

overwrite

Replace an existing backend with the same name.

input

Named list of backend inputs such as plink_prefix, geno_file, output_dir, and thread settings.

sample_ids

Unique sample identifiers in exact Q-matrix row order.

k_values

Positive integer K values greater than or equal to two.

replicates

Independent replicates per K and backend.

seed

Base seed used to derive deterministic task seeds.

fail_if_none

Error when none of the requested backends is available.

Value

Backend constructors return plugin or registry objects. ancestry_backend_status() returns a data.table. run_ancestry() returns canonical results by backend, an execution record table, and the backend availability table.

Details

A third-party backend supplies availability, validation, execution, and parsing callbacks. The parser must return a validated PopgenVCFAncestryReplicate; downstream label alignment, consensus estimation, K selection, plotting, and reporting are therefore independent of the native backend format.