Overview

UCALM combines three steps in one framework: unsupervised subgroup inference, subgroup-specific GWAS and layered meta-integration. The first step infers genetically homogeneous subgroups directly from genotype data. The second step runs association testing within each inferred subgroup. The final step integrates subgroup-level association evidence so that shared, ancestry-correlated and population-specific signals can all contribute to the final result.

When UCALM Helps

Use UCALM when the study cohort is genetically heterogeneous and the subgroup structure is not fully captured by existing metadata. It is most useful when samples come from multiple ancestries, breeds, breeding lines, companies, regions or admixed backgrounds, or when conventional GWAS shows inflation, masked peaks or inconsistent signals across known groups.

• Use the individual-level data path when MVP needs to infer latent population structure and run association testing within inferred subgroups.
• Use the summary-level data path when subgroup GWAS has already been run and you only need the UCALM layered integration step.
• Use conventional pooled GLM or MLM when the cohort is genetically homogeneous and subgroup-specific effects are not expected.

Path 1: Individual-level Data

Use --ucalm for the full individual-level data path. This command starts from PLINK genotype files and phenotype records, infers subgroups and then performs subgroup GWAS followed by UCALM integration.

Input: PLINK 1 binary dataset prefix with --bfile (.bed/.bim/.fam) or PLINK 2 PGEN dataset prefix with --pfile (.pgen/.pvar/.psam), a phenotype file with --pheno, the target trait column with --pheno-pos, and optional covariates, MAF, thread and clustering parameters. See Genotype Files, Phenotype File and Covariates in Phenotype File.

mvp --ucalm \
    --bfile demo \
    --pheno demo.phe \
    --pheno-pos 2 \
    --npc-cluster 10 \
    --use-umap \
    --use-kdtree \
    --threads 32 \
    --out demo

• Analysis steps: genomic relationship matrix (GRM) construction, eigendecomposition of the GRM to derive PCs, variance-weighted PCs, UMAP, AutoHDBSCAN, subgroup GWAS and UCALM layered integration.
• Clustering parameters: set the number of PCs used for clustering (--npc-cluster), use a KD tree for nearest neighbor search (--use-kdtree), and adjust the UMAP neighborhood size (--umap-nn) and minimum distance parameter (--umap-md) to control the local and global structure and the compactness of the embedding.
• Output: the individual-level data path writes cluster assignments, UMAP coordinates, subgroup variance summaries and a final association table. See Outputs for the file list.

Path 2: Summary-level Data

Use the summary-level data path when subgroup GWAS summary statistics have already been generated. In this path, UCALM skips genotype clustering and directly performs layered meta-integration across population-level summary statistics.

Input: at least two harmonized summary statistics files. Each file must include a header and the columns SNP CHR POS A1 A2 MAF BETA SE PVAL N. Marker IDs, chromosome and position, effect allele coding, reference genome build and sample-size definitions must be consistent across files.

Requires: summary statistics prepared as described in Summary Statistics Input.

mvp --meta \
    --sumstat pop1.sumstat,pop2.sumstat,pop3.sumstat \
    --meta-method 1 \
    --threads 32 \
    --out demo

• Analysis steps: MVP keeps SNPs shared across the summary statistics files, checks chromosome, position and allele coding against the first file, flips frequency and beta when A1/A2 are reversed, applies missing-value, MAF and minor allele count filters, and then performs UCALM layered integration.
• Default: UCALM uses a 1 Mb window by default to provide local allele frequency structure for the ancestry-correlated component.
• Output: demo.assoc.txt columns: SNP, CHR, POS, A1, A2, subgroup MAF columns, subgroup BETA, SE and PVAL columns, plus the final UCALM_PVAL column.

Computational Acceleration

To improve computational efficiency, UCALM uses several acceleration strategies during clustering. The table below lists the main strategies and the parameters that control them.

Outputs

Several files will be generated in the work directory:

demo.cluster.txt: the cluster results for all individuals. In the ambiguity column, 0 indicates a core sample and 1 indicates an ambiguous reassigned sample.

demo.cluster.umap.txt: the UMAP results for all individuals.

demo.c*.vars.txt: the estimated variance and heritability of all random effects in each subgroup.

demo.assoc.txt: the UCALM association results.

UCALM_PVAL is the final layered meta-integration P-value. DOMINANT reports the dominant UCALM component label for the marker: homogeneous, ancestry-correlated or population-specific.

Result Checks

Use the checks below before interpreting UCALM outputs.