MKado Documentation

MKado is a modern Python implementation of the McDonald-Kreitman test toolkit for detecting selection in molecular evolution.

Note

MKado requires Python 3.12 or later.

Features

• Standard MK test: Classic 2x2 contingency table with Fisher’s exact test

• Polarized MK test: Uses a second outgroup to assign mutations to lineages

• Asymptotic MK test: Frequency-bin alpha estimates with exponential extrapolation (Messer & Petrov 2013)

• Imputed MK test: Corrects for slightly deleterious mutations by imputation (Murga-Moreno et al. 2022)

• Tarone-Greenland α_TG: Weighted multi-gene estimator (Stoletzki & Eyre-Walker 2011)

• Omega decomposition: dN/dS plus adaptive (ω_a) / non-adaptive (ω_na) rates with 95% CIs (Gossmann, Keightley & Eyre-Walker 2012)

• Bootstrap CI option: --ci-method bootstrap runs a case-resampling bootstrap as an alternative to the parametric Monte Carlo CI; bootstrap CI on imputed alpha when --bootstrap > 0

• Alternate genetic codes: Support for 24 NCBI genetic code tables (mitochondrial, plastid, etc.)

• VCF input: Go directly from VCF + reference + GFF3 to MK test results

• Batch processing: Process multiple genes with parallel execution

• Volcano plots: Visualize batch results with publication-ready volcano plots

• Multiple output formats: Pretty-print, TSV, and JSON

Quick Example

# Standard MK test
mkado test alignment.fa -i "dmel" -o "dsim"

# Asymptotic MK test
mkado test alignment.fa -i "dmel" -o "dsim" -a

# Batch process a directory
mkado batch alignments/ -i "dmel" -o "dsim"

# Directly from VCF files
mkado vcf --vcf pop.vcf.gz --outgroup-vcf out.vcf.gz --ref genome.fa --gff genes.gff3

Contents:

• Installation
  • Requirements
  • Installing with pip
  • Installing with uv (Recommended)
  • Development Installation
  • Running Tests
  • Verifying Installation
• Getting Started Tutorial
  • Prerequisites
  • The McDonald-Kreitman Test
  • Your First MK Test
  • Interpreting Results
  • Asymptotic MK Test
  • Allele Polarization
  • Polarized MK Test
  • Frequency Filtering Options
  • Genetic Code Tables
  • Output Formats
  • Working with VCF Data
  • Working with Ortholog Alignments (OrthoMaM-style projection)
  • Next Steps
  • References
• Batch Processing Workflow
  • Basic Batch Processing
  • Per-gene vs Aggregated Modes
  • File Organization
  • Asymptotic Batch Analysis
  • Parallel Processing
  • Output Formats
  • Multiple Testing Correction
  • Volcano Plots
  • File Filtering
  • Advanced Options
  • Example Workflow
  • References
• VCF Input Mode
  • Required Input Files
  • Basic Usage
  • Gene Selection
  • Analysis Modes
  • How It Works
  • Edge Cases
  • Parallel Processing
  • Output Formats
  • Preparing Your Data
  • Comparison with FASTA Mode
• Asymptotic MK Test
  • Background
  • The Key Insight
  • The α(x) Formula
  • SFS Construction: At-x vs Above-x
  • Determining Derived Allele Frequency
  • Model Fitting and Selection
  • Usage
  • Output
  • The Alpha(x) Plot
  • Frequency Cutoffs
  • Comparison with Other Methods
  • When to Use Asymptotic α
  • Interpreting Results
  • References
• Imputed MK Test
  • Background
  • The Key Insight
  • The Imputation Formula
  • DFE Fractions
  • Usage
  • Output
  • Comparison with Other Methods
  • When to Use the Imputed MK Test
  • Interpreting Results
  • Choosing the DAF Cutoff
  • Reference
• Tarone-Greenland Alpha (α_TG)
  • Background
  • The NI_TG Formula
  • Usage
  • Output
  • Comparison with Other Methods
  • When to Use α_TG
  • Reference
• Direction of Selection (DoS)
  • Background
  • The DoS Formula
  • Interpretation
  • Advantages over NI
  • Output
  • Example Calculation
  • Edge Cases
  • Reference
• Omega Decomposition (ω, ω_a, ω_na)
  • Background
  • The decomposition
  • Site counting
  • When ω_a / ω_na are reported (and when they are not)
  • Confidence intervals
  • Edge cases
  • References
• File Formats and Input Requirements
  • FASTA Format
  • Alignment Requirements
  • Sequence Naming Conventions
  • Ingroup and Outgroup
  • Handling Special Cases
  • Common Problems
  • VCF Mode Input Files
  • Example Data
• Python API Reference
  • Quick Start
  • Core Classes
  • Analysis Functions
  • Usage Examples
  • Plotting Functions

Citation

If you use MKado in your research, please cite:

Rivera-Colón, A. G., Rehmann, C. T., & Kern, A. D. (2026). MKado: a toolkit for McDonald-Kreitman tests of natural selection. bioRxiv. https://doi.org/10.64898/2026.03.02.709122

Indices and tables

• Index

• Module Index

• Search Page