Quick Start

Start with a small and explicit command before launching a full analysis. The examples below assume that genotype files use the prefix data/geno, the phenotype file is data/pheno.txt, and output files will be written under result/.

# GLM GWAS
mvp --glm --bfile data/geno --pheno data/pheno.txt --out result/glm

# MLM GWAS
mvp --mlm --bfile data/geno --pheno data/pheno.txt --out result/mlm

# PCA
mvp --pca --bfile data/geno --npc 5 --out result/pca

# GRM construction
mvp --make-grm --bfile data/geno --out result/grm

• Use --glm first to verify basic phenotype, genotype and covariate formatting.
• Use --mlm when relatedness or population structure needs stronger control.
• Use --pca or --make-grm separately when you want to inspect intermediate files.
• Use a fresh --out prefix for each run to avoid overwriting previous output.

Output Prefix and Threads

Use --out to set the output prefix and --threads to set the number of CPU threads. This rule applies across GLM, MLM, PCA, GRM, clustering, meta-analysis and plotting workflows.

Output prefix rule. MVP appends suffixes such as .assoc.txt or plot file extensions to the prefix. The prefix itself should not include those suffixes.

GLM Analysis

Use --glm as the first GWAS scan to verify phenotype, genotype, covariate and association-output formatting.

Requires: phenotype file and one genotype prefix. See Phenotype File and Genotype Files.

mvp --glm \
    --bfile demo \
    --pheno demo.phe \
    --pheno-pos 2 \
    --dcovar 4,5 \
    --qcovar 6 \
    --maf 0.01 \
    --out result/glm_demo

• Output: association table under the selected --out prefix.
• Use --add for additive genetic effect or --dom for dominant effect. If neither is supplied, additive effect is used.
• Add covariates only after confirming their column positions and data types in the input-format section.

MLM Analysis

Use --mlm when population structure or kinship may inflate GLM statistics. If no --grm is provided, MVP can construct the relationship matrix from genotype data.

Requires: phenotype file, genotype prefix and optionally a GRM prefix. See Relationship Matrix File.

mvp --mlm \
    --bfile demo \
    --pheno demo.phe \
    --pheno-pos 2 \
    --npc 3 \
    --out result/mlm_demo

• Output: association table and model logs under the selected --out prefix.
• --npc adds principal components to the fixed-effect part of the GWAS model.
• --max-iter controls the maximum number of variance component iterations.
• --mlm-path mkm uses marker-by-marker variance handling for full MLM scans; --mlm-path emmax estimates variance once and reuses it for faster approximate scans.
• For production MLM runs, keep the GRM prefix, version and command line together with the output.

Multi-trait Analysis

Pass multiple phenotype columns to analyze several traits in one command.

Requires: one phenotype file whose selected trait columns share the same individual ID column.

mvp --mlm \
    --bfile demo \
    --pheno demo.phe \
    --pheno-pos 2,3,4 \
    --out result/mlm_multi_trait

• Output: trait-specific columns in the association result table.
• Each selected trait may have missing values encoded as NA.
• If --vg and --ve are supplied, provide one value per selected trait in the same order as --pheno-pos.

PCA

Use --pca with genotype data or a pre-computed GRM to inspect population structure.

Requires: genotype prefix or GRM prefix, plus the requested number of PCs.

mvp --pca --bfile demo --npc 5 --out result/pca
mvp --pca --grm demo_grm --npc 5 --out result/pca_from_grm

• Output: PC scores and variance summary files.
• Use PCA output for structure review, plotting and clustering input.

Model correction. For GLM or MLM, specify --npc in the association command rather than passing a PC file with --pc.

GRM Construction

Use --make-grm to construct reusable genomic relationship matrix files.

Requires: genotype prefix. The resulting GRM can be reused by MLM, PCA and clustering workflows.

mvp --make-grm \
    --bfile demo \
    --grm-method 1 \
    --out result/demo_grm

• Output: GRM binary matrix and ID files under the selected prefix.
• --grm-method selects the relationship-matrix construction method.
• Use --bitwise-grm for BED-based raw additive GRM construction when that optimized path is appropriate.
• Use --float-prec if you need lower memory use for matrix-heavy steps.

Population Clustering

Use --cluster or --auto-cluster for HDBSCAN-based clustering from genotype, GRM or PC input.

Requires: one structure input source. See Principal Component File and Relationship Matrix File.

mvp --cluster --bfile demo --npc-cluster 3 --out result/cluster
mvp --cluster --pc demo.pc --npc 3 --out result/cluster_from_pc

• Output: cluster labels and optional parameter/embedding files.
• Use clustering when known population labels are unavailable or need cross-checking.
• When clustering from genotype data, MVP first derives the requested number of PCs for clustering.
• Use --npc-cluster for the number of PCs used in clustering from genotype or GRM input.
• --use-umap can add UMAP before clustering; tune --umap-nn and --umap-md only after the basic command works.
• --use-kdtree can reduce memory cost for clustering neighborhood queries.

mvp --auto-cluster \
    --bfile demo \
    --npc-cluster 10 \
    --use-umap \
    --umap-nn 15 \
    --umap-md 0.1 \
    --out result/cluster_umap

Parameter compatibility. Do not combine --grid with --use-umap. Grid optimization is for the automatic clustering workflow without UMAP.

GPU Acceleration

GPU options are available only when MVP is built with CUDA support. Use GPU acceleration mainly for computationally intensive MLM workflows and benchmark CPU versus GPU results on a representative subset before running a full dataset.

Requires: CUDA-enabled MVP build and a working CUDA runtime.

mvp --mlm \
    --bfile demo \
    --pheno demo.phe \
    --device cuda \
    --gpus 0,1 \
    --evd-method mg \
    --out result/mlm_gpu

Runtime validation. The current source tree still has a few differences between CLI help text and later parameter validation. This table lists values that pass the current runtime checks.

Benchmark Mode

Use benchmark mode to write phase-level timing information. This is useful when comparing CPU and GPU settings, tuning --step, or preparing a performance report for a release.

Requires: any valid analysis command plus benchmark output options.

mvp --mlm \
    --bfile demo \
    --pheno demo.phe \
    --benchmark \
    --benchmark-out result/mlm_benchmark \
    --out result/mlm

MVP writes <benchmark-out>.timing.json. Keep this JSON file with the association output so runtime comparisons can be reproduced later.

• Run benchmark commands on an otherwise quiet machine when possible.
• Use the same input files and model options when comparing two devices.
• Record CPU model, GPU model, memory size and MVP version together with the timing file.

Plot Generation During Analysis

When the plotting module is enabled, add --plot to generate figures after analysis. This is convenient for routine GWAS runs because association tables and plots are generated from the same command and output prefix.

Requires: a plotting-enabled MVP build and an analysis that produces plot-ready output.

mvp --glm \
    --bfile demo \
    --pheno demo.phe \
    --plot \
    --plot-theme nature \
    --out result/glm_plot

• Output: association table plus figures under the selected prefix.
• Use --plot-only from an existing result file when you only need to regenerate figures.