Population-structure comparison and validation tools — population

Tools for label-switching-aware membership comparison, replicate reproducibility, K selection, optional external population-structure engines, and deterministic validation.

Usage

align_cluster_labels(target, reference)

compare_q_matrices(target, reference)

structure_reproducibility(matrices, reference = 1L)

select_structure_k(
  diagnostics,
  additional_votes = NULL,
  tolerance_fraction = 0.02
)

run_faststructure(
  structure_executable = "structure.py",
  choosek_executable = "chooseK.py",
  plink_prefix,
  k_values,
  output_dir = ".",
  seed = 42L,
  timeout_seconds = 14400
)

run_snmf(
  geno_file,
  k_values,
  repetitions = 5L,
  entropy = TRUE,
  seed = 42L,
  project_mode = "new",
  threads = 1L
)

run_population_structure_validation(integration = FALSE, seed = 42L)

Arguments

target: Numeric sample-by-K membership matrix to align or compare.
reference: Reference membership matrix, or the reference replicate index/name.
matrices: Named list of equal-dimensional membership matrices.
diagnostics: Data frame containing K and one or more supported diagnostic columns.
additional_votes: Optional named integer vector or data frame containing backend-native method and K recommendations.
tolerance_fraction: Fraction of the observed metric range used by the parsimonious near-optimum rule when standard errors are unavailable.
structure_executable: Path or command name for fastStructure structure.py.
choosek_executable: Path or command name for fastStructure chooseK.py.
plink_prefix: Prefix of PLINK BED/BIM/FAM files.
k_values: Integer values of K to evaluate.
output_dir: Directory for external-program output.
seed: Random seed.
timeout_seconds: Maximum wall-clock seconds allowed per subprocess call (each K value's structure.py run, and the final chooseK.py run) before it is killed and treated as a failure.
geno_file: LEA-format .geno file.
repetitions: Number of sNMF repetitions per K.
entropy: Whether sNMF computes cross entropy.
project_mode: LEA project mode passed to LEA::snmf.
threads: Number of CPUs used by LEA across K and repetition runs.
integration: Run the optional adegenet DAPC integration fixture.

Value

Function-specific lists or data tables containing aligned membership matrices, diagnostics, reproducibility metrics, or validation checks.

References

Alexander, Novembre and Lange (2009). Fast model-based estimation of ancestry in unrelated individuals. Genome Research.

Raj, Stephens and Pritchard (2014). fastSTRUCTURE: variational inference of population structure in large SNP data sets. Genetics.

Frichot et al. (2014). Fast and efficient estimation of individual ancestry coefficients. Genetics.

Jombart, Devillard and Balloux (2010). Discriminant analysis of principal components. BMC Genetics.