run clumppling

This function runs the clumppling algorithm by calling the python module. If you use this function, make sure that you cite the relevant paper by Liu, Kopelman, and Rosenberg (2024).

gt_clumppling(
  input_path,
  input_format = "admixture",
  use_rep = TRUE,
  merge = TRUE,
  cd_method = "louvain",
  use_best_pair = TRUE,
  extension = ".Q",
  seed = NULL,
  output_path = NULL
)

Arguments

input_path

either a gt_admix object, a list of Q matrices, or the path where the Q files are stored, either a directory or a zip archive

input_format

a string defining the format of the input files, one of 'admixture' (default),'structure','fastStructure' or 'generalQ'. Only used if input_path is a path.

use_rep

boolean, whether to use representative modes (alternative: average), defaults to TRUE

merge

boolean, whether to merge two clusters when aligning K+1 to K, defaults to TRUE

cd_method

the community detection method to use, one of 'louvain' (default), 'leiden', 'infomap', 'markov_clustering', 'label_propagation', 'walktrap', 'custom'

use_best_pair

boolean, whether to use best pair as anchor for across-K alignment (alternative: major), defaults to TRUE

extension

(optional) if loading from files rather than a gt_admix object, specify the extension e.g. ".Q" or ".indivq"

seed

(optional) an integer used to set the random seed in python, so that community detection (e.g. 'louvain') is reproducible. Defaults to NULL (no seed is set).

output_path

deprecated and ignored. Clumppling functions are now called directly from R, and their outputs are returned as R objects rather than written to files.

Value

a list of class gt_clumppling containing:

  • N: number of individuals

  • K_range: vector of K values analyzed

  • mode_replicates: a list of replicate indices for each mode

  • cost_acrossK: a named list of costs for each pairwise K alignment

  • aligned_modes: a list of data.frames, each data.frame is a Q-matrix

  • mode_stats: a data.frame with the size, cost and performance (average similarity among replicates) of each mode

Details

If you would like to generate an annotated autoplot from your gt_clumppling object, ensure that all individuals from the same population are adjacent to one another in the Q-matrix or gt_admix object supplied to gt_clumppling. Autoplot 'group' argument requires that all individuals from the same group are adjacent.

Q matrices from a gt_admix object (or a list of Q matrices) are passed directly to python. Q files in a directory (or a zip archive) are parsed by clumppling itself (using a temporary directory), which allows the use of the different formats supported by clumppling. Note that, for 'admixture' files with extension '.indivq', and for 'structure' files, clumppling uses the population labels in the files to reorder individuals so that individuals from the same population are adjacent.

References

X. Liu, N. M. Kopelman, N. A. Rosenberg (2024) Clumppling: cluster matching and permutation program with integer linear programming. Bioinformatics 40(1): btad751. doi: https://doi.org/10.1093/bioinformatics/btad751