Analysis Tools and Utilities

High-level file-backed analysis helpers and label-table utilities.

Genetic sex checking

snputils.run_sex_check(snp_source, reported_sex=None, *, results_path=None, assume_x=False, low_information_threshold=500)

Run sex checking from a genotype path or an in-memory SNPObject.

File-backed input uses snputils readers and loads chromosome-X genotypes only for BED, PGEN, BCF, and consistently named VCF inputs. BGEN probabilities are not hard-called implicitly.

For an already-loaded SNPObject, use sex_check() directly. The file-backed helper accepts VCF, BCF, BED, and PGEN hard-call inputs and can write the resulting TSV through results_path.

GWAS and admixture mapping

snputils.run_gwas(phe_path, snp_path, results_path='gwas.tsv.gz', phe_id=None, batch_size=256, memory=None, return_results=True, quantitative=None, verbose=False, covar=None, covar_path=None, covar_col_nums=None, covar_variance_standardize=False, ci=None, adjust=False, keep_path=None, remove_path=None, exclude_path=None, vcf_backend='polars')

Run variant-level association testing.

phe_path may be a phenotype file path or an in-memory PhenotypeObject. snp_path may be a genotype file path, reader, or in-memory SNPObject. covar may be a covariate file path or an in-memory CovariateObject; covar_path is retained as a backward-compatible alias. phe_id is required only when the phenotype input is a file path. Results are written to results_path (default: gwas.tsv.gz).

snputils.run_admixture_mapping(phe_path, lai_source=None, results_path='admixmap.tsv.gz', phe_id=None, batch_size=256, keep_hla=False, memory=None, return_results=True, quantitative=None, verbose=False, covar=None, covar_path=None, covar_col_nums=None, covar_variance_standardize=False, ci=None, adjust=False, keep_path=None, remove_path=None)

Run window-level admixture mapping from a local ancestry file or LAI object.

Parameters:

• phe_path – Phenotype file path or in-memory PhenotypeObject.

• lai_source – Local ancestry source. Pass an MSP/FLARE file path or an in-memory LocalAncestryObject.

• results_path – Output TSV path or directory (default: admixmap.tsv.gz).

• phe_id – Phenotype column name to analyze. Required when phe_path is a file path; inferred from PhenotypeObject.phenotype_name for in-memory phenotype input.

• covar – Covariate file path or in-memory CovariateObject. covar_path is retained as a backward-compatible alias.

Both functions accept file paths or in-memory objects and return a DataFrame with per-variant statistics suitable for Visualization.

Sample labels

snputils.read_labels(file, sep='\t')

Read an individual-label table used by dimensionality-reduction plots.

The returned DataFrame has indID coerced to string and must include at least indID and label columns.

Label tables must include indID and label columns. They are used by scatter plots, mdPCA, and maasMDS.