MVP

Tutorial

Core concepts, first run, feature map, command structure, version and help checks.

Section 1

Introduction

MVP is a memory-efficient, visualization-enhanced and parallel-accelerated command-line tool for genome-wide association study. This tutorial follows the style of a practical software manual: prepare input files, select an analysis mode, run MVP, then inspect outputs.

What is MVP

MVP is implemented in C++17 for scalable GWAS workflows. It is designed as a command-line program: each run starts from one major function flag, reads well-defined input files, and writes analysis tables or plots under the output prefix. The same phenotype and genotype files can be reused across GLM, MLM, PCA, GRM construction and downstream population-aware workflows.

  • --glm: General Linear Model.
  • --mlm: Mixed Linear Model.
  • --pca: Principal component analysis.
  • --make-grm: Genomic relationship matrix construction.
  • --cluster or --auto-cluster: Unsupervised adaptive population clustering.
  • --ucalm: Unsupervised adaptive Clustering-based Association and Layered Meta integration.
  • --meta: Meta-analysis for multiple GWAS summary statistics files.
  • --plot and --plot-only: Visualization after analysis or from existing results.

Typical workflow. Prepare phenotype and genotype files, run PCA or GRM if needed, select GLM or MLM for association analysis, then use plotting or meta-analysis commands to summarize the results.

Before You Start

  • GWAS scans the genome for statistical associations between genetic markers and measured traits.
  • Population structure can create false signals; PCA, GRM and MLM help control relatedness and subgroup effects.
  • Manhattan and Q-Q plots help review association peaks, background inflation and possible model issues.
  • MVP workflow usually starts from phenotype and genotype files, then moves through GLM, MLM, PCA, GRM, meta-analysis or plotting as needed.

First Run

Use a small GLM command as your first end-to-end check. This verifies that MVP starts correctly, your input prefixes are valid, and the output path is writable. 

mvp --help

mvp --glm \
    --bfile data/geno \
    --pheno data/pheno.txt \
    --pheno-pos 2 \
    --out result/first_glm
  • Use --help first to confirm that the analysis modules you need are available in the current build.
  • The genotype input should be provided as a prefix such as data/geno, not as a single .bed or .pgen file path.
  • After the run, check the association output under result/first_glm.assoc.txt.

Main Features

  • MVP accepts PLINK 1 binary genotype prefixes with --bfile and PLINK 2 PGEN prefixes with --pfile.
  • Multi-trait phenotype analysis with comma-separated phenotype columns.
  • CPU execution by default, optional CUDA acceleration for supported builds.
  • Automatic plot generation for association and PCA outputs when plotting is enabled.
  • Optional compile-time modules for clustering, meta-analysis and plotting.
FeatureWhat it is used forMain options
Association scanSingle-trait or multi-trait GWAS with additive or dominant effects.--glm, --mlm, --add, --dom
Population structurePCA correction, clustering, subgroup GWAS and meta-analysis.--npc, --cluster, --pop-class
Relationship matrixGRM construction for MLM and PCA from relationship matrix.--make-grm, --grm, --grm-method
VisualizationGenerate Manhattan, Q-Q, PCA and density-style plots from analysis outputs.--plot, --plot-only, --plot-theme
PerformanceThreaded CPU execution, optional CUDA execution and benchmark reports.--threads, --device, --benchmark

Command Structure

MVP uses one main function flag followed by input, model, runtime and output options. In most cases, use only one function flag in a command. For example, do not run --pca and --make-grm in the same command. 

mvp [Function] [Option]

For example:

mvp --glm --bfile data/geno --pheno data/pheno.txt --out result/glm
Option groupExamplesNotes
Function--glm, --mlm, --pca, --metaSelects the major analysis mode.
Input--pheno, --bfile, --pfile, --grmPoints to phenotype, genotype, GRM or summary files.
Model--pheno-pos, --dcovar, --qcovar, --mafDefines trait columns, covariates and filtering.
Runtime--threads, --device, --stepControls CPU/GPU resources and block size.
Output--out, --plot, --benchmark-outControls output prefix, figures and benchmark records.

Check Version and Help

mvp --version
mvp --help

Use --help before starting a new analysis to confirm which optional modules are available in your build. If a flag shown in this tutorial is missing from the help message, rebuild MVP with the corresponding module enabled or use a release binary that includes that feature.

Reproducibility tip. Save the output of mvp --version, the full command line and the input file prefixes together with your result files.