fineSTRUCTURE & ChromoPainter: A Step-by-Step Guide

TL;DR — From Painting to Clusters in Seven Practical Steps

Phase genomes and align to a recombination map; run ChromoPainter v2 in EM mode to estimate global Ne and μ, then "paint" haplotypes and merge outputs with ChromoCombine to build a coancestry matrix. Feed that matrix into fineSTRUCTURE, run MCMC with built-in convergence diagnostics, and interpret the cluster tree against metadata and PCA/ADMIXTURE. When you need admixture dates and source profiles, pass the painted output to GLOBETROTTER or fastGLOBETROTTER.

Why Haplotype Painting Outperforms Frequency-Only Methods

Simulated data illustrate how haplotype-aware painting refines structure: linked coancestry heatmaps and corresponding PCA separate closely related groups more clearly than unlinked summaries. (Lawson D.J. et al. (2012) PLOS Genetics)

Allele-frequency approaches (PCA or ADMIXTURE) capture broad structure, but they often blur very recent common ancestry. Haplotype methods do better here because long shared segments carry time-rich information. ChromoPainter implements the Li–Stephens copying model, representing each recipient haplotype as a mosaic copied from donor haplotypes; fineSTRUCTURE then clusters samples using the coancestry counts implied by those copying paths. This combination has resolved striking geography-matched clusters in dense sampling projects (for example, the UK's PoBI map), revealing subtle differentiation that frequency methods alone struggled to detect.

Plain-English takeaway: if your question involves recent splits, cryptic isolates, or fine-scale stratification relevant to downstream association or demography, haplotype painting + fineSTRUCTURE gives you a sharper lens than SNP frequencies alone.

What You Get and Where It Helps

• A Coancestry Matrix You Can Trust. Painting converts millions of SNPs into a compact "who copies from whom" summary (counts or chunk lengths). fineSTRUCTURE consumes this matrix to infer clusters and a hierarchical tree via MCMC, with new diagnostics to confirm you ran it long enough.
• Actionable, Fine-Scale Clusters. You can localize isolates, resolve substructure within admixed cohorts, and build stratification covariates that go beyond PC1/PC2. This is especially useful when preparing reviewer-ready deliverables in a Population Structure Analysis report.
• Admixture Timelines and Sources. With GLOBETROTTER, the same painted data can identify and date admixture events up to roughly the last ~4,500 years and describe plausible source profiles; fastGLOBETROTTER accelerates this substantially with minimal accuracy loss.

Foundations, Inputs, and Sizing Thresholds

• Copying Model Under the Hood. ChromoPainter v2 uses the Li–Stephens HMM to model each chromosome as an imperfect mosaic of others, governed by mutation (θ) and recombination/switch (ρ) parameters. That's why EM estimation of global Ne and μ is part of standard setup.
• Manuals That Matter. The fineSTRUCTURE/ChromoPainter v2 manual covers formats, EM, chunking, and ChromoCombine; the fineSTRUCTURE 4 manual adds explicit MCMC convergence tests, along with HPC-friendly staging. Keep both at hand when writing Methods.
• Scale Tips. Thousands of samples are feasible: split the genome into chunks, parallelize painting across recipients and/or chromosomes, then merge with ChromoCombine; run clustering afterward. Your compute plan becomes predictable and repeatable in a Population Structure Analysis engagement.

Step-By-Step Workflow

1) Prepare Inputs (Phasing And Maps)

• Phasing: Phase autosomes with your preferred tool; ensure consistent build/strand and allele codes across donors and recipients.
• Genetic Map Alignment: Supply a recombination map; if a local map is unavailable, use a well-supported map for your build, acknowledging limitations in Methods.
• QC: Remove problematic regions following your lab SOP; verify sample/variant filters align with earlier PCA QC decisions so that painting reflects biology, not batch.

Why this matters: the copying model assumes well-phased haplotypes and realistic recombination distances; garbage in, noisy copying out.

2) Estimate Global Parameters (EM In ChromoPainter v2)

Run ChromoPainter v2 in EM mode on a representative subset to infer Ne (effective population size) and μ (per-site mutation/switch rate). Record these values for full runs and document exactly which chromosomes or windows you used for EM; consistency makes runs reproducible and speeds reviewer checks.

Pragmatic tips

• Use multiple seeds and compare EM solutions; keep logs for your methods pack.
• If the cohort is highly heterogeneous, run EM on a balanced subset across major groups.

3) Paint At Scale (Chunk, Parallelize, Merge)

• Chunking Strategy: Split chromosomes into manageable segments to distribute across an HPC or cloud scheduler; ensure chunk boundaries respect recombination map continuity.
• Parallel Execution: Parallelize by recipient, chromosome, or chunk, depending on your cluster; keep per-job resource caps modest to avoid noisy neighbors.
• ChromoCombine: After painting, merge chunk-level outputs into per-chromosome or genome-wide files; double-check column order and sample IDs before downstream steps.

4) Build The Coancestry Matrix

Aggregate the copying counts (or chunk lengths) to create a dense coancestry matrix where rows are recipients and columns are donors. Inspect diagonals and row/column sums to catch I/O mishaps; visualize a pilot heatmap to confirm expected blocks (e.g., by geography or known pedigree). This matrix is the single input fineSTRUCTURE needs to infer clusters.

From painted haplotypes to clusters: fineSTRUCTURE's coincidence matrix and MAP tree derived from the coancestry matrix, with performance gains over frequency-only models in separating subtle splits. (Lawson D.J. et al. (2012) PLOS Genetics)

5) Cluster With fineSTRUCTURE (MCMC and Tree Building)

• Run MCMC: Provide the coancestry matrix to fineSTRUCTURE and run with adequate burn-in and sampling.
• Convergence Diagnostics: Use the new diagnostics (fineSTRUCTURE 4) to ensure the chain ran long enough; compare independent chains where feasible and summarize posterior support on major splits.
• Tree And Clusters: Extract the maximum a posteriori tree and cluster labels; keep the state files so you can trace decisions in your Population Structure Analysis report.

6) Validate Convergence and Stability (Don't Skip)

• Chain-to-Chain Agreement: Concordance of large clades across chains suggests stability; if not, extend runs or revisit chunking.
• Sensitivity To Chunking Seeds: Repaint a small subset with alternate chunk boundaries or seeds; stable clusters should persist.
• Cross-Evidence: Compare clusters with PCA/ADMIXTURE; compatible signals build confidence, while disagreements flag where sampling or donor choices need refinement.

European coancestry heatmaps reveal haplotype-sharing structure; juxtaposed ADMIXTURE barplots show how frequency-based assignments align yet can miss fine-scale patterns captured by painting. (Lawson D.J. et al. (2012) PLOS Genetics)

7) Interpret Clusters And (Optionally) Date Admixture

• Interpretation: Map clusters to geography or metadata; examine coancestry heatmaps for donor-recipient patterns (e.g., isolate blocks or recent migrants).
• Admixture Dating: Feed the painted output into GLOBETROTTER to identify and date events and reconstruct plausible sources within roughly the last ~4,500 years; fastGLOBETROTTER yields 4–20× speed-ups with similar accuracy. Record the null-individual and bootstrapping choices.

Sampling of DNA segment pairs in fastGLOBETROTTER relative to GLOBETROTTER. (Wangkumhang P. et al. (2022) Genome Research)

Quality Checks, Pitfalls, and Cross-Checks

1) Painting Bias from Donor Choice

If donors lack coverage of plausible ancestry sources, copying becomes biased. Broaden donors or restructure donor panels before re-painting; your Methods should state donor selection logic.

2) Over-Clustering from Aggressive Chunking

Excessively small chunks or inconsistent chunk boundaries can inflate spurious splits. Use recommended chunk sizes, then test stability by re-running a subset with coarser boundaries. The manual's computational considerations provide guidance.

3) Misinterpreting fineSTRUCTURE Trees

A tree summarizes coancestry patterns, not necessarily a strict population phylogeny. Anchor your narrative in geography and external evidence (e.g., historical records or reference panels). Dense regional sampling (as in PoBI) yields geography-coherent clusters while still accommodating admixture signals.

4) Under-Powered EM Estimation

Running the EM step on a narrow subset can mis-estimate Ne/μ. Re-estimate on a stratified subset and confirm stability across seeds; document chosen values and justification.

5) Under-Running The MCMC

If diagnostics flag insufficient mixing, extend the chain and revisit thinning/burn-in settings. Cite convergence checks in Methods to preempt reviewer questions.

Minimal Reporting Pack (Reviewer-Ready)

Methods (boilerplate to adapt):

"We phased autosomes and aligned variants to a standard recombination map. Using ChromoPainter v2, we estimated global Ne and μ by EM on a representative subset and then painted all samples in parallel across chromosome chunks, merging outputs with ChromoCombine. We aggregated chunk counts into a genome-wide coancestry matrix and clustered with fineSTRUCTURE, assessing MCMC convergence with the provided diagnostics and comparing independent chains. We validated key splits against PCA/ADMIXTURE and, where relevant, dated admixture events with GLOBETROTTER/fastGLOBETROTTER (bootstrapping and null-individual settings documented)."

Figure set for the report:

1. Coancestry heatmap ordered by cluster labels.
2. fineSTRUCTURE tree with posterior support on major clades.
3. Cluster-by-geography map or bar chart.
4. Stability diagnostics across chains/chunking seeds.
5. GLOBETROTTER admixture curves and date estimates (optional).

Where This Fits Your Service Stack

• Population Structure Analysis service: deliverables include the painted coancestry matrix, cluster labels, a fineSTRUCTURE tree, and optional GLOBETROTTER dating—all tied to a reproducible compute plan.
• PCA QC and ADMIXTURE K selection: use earlier outputs to vet sampling, confirm broad structure, and define donor panels before you invest in painting and MCMC.
• Downstream modeling: use clusters to stratify association testing or to interpret rare-variant burden analyses in isolates.

FAQ — fineSTRUCTURE & ChromoPainter in Practice

Conclusion & Next Steps

When your project needs fine-scale structure, recent relatedness, or historical admixture timing, ChromoPainter + fineSTRUCTURE provides the right level of resolution—and the GLOBETROTTER suite extends it to timelines and sources. The winning playbook is simple and reproducible: phase and map, EM for Ne/μ, paint and merge, build the coancestry matrix, cluster with convergence checks, then interpret and (optionally) date.

If you want a turnkey path from raw genotypes to a reviewer-ready structure report, start a Population Structure Analysis project: we'll scope the donor panel, EM subset, chunking and HPC budget, and deliver the full pack—coancestry heatmaps, fineSTRUCTURE trees, stability diagnostics, and (when needed) GLOBETROTTER/fastGLOBETROTTER dating—designed to integrate cleanly with your PCA QC and ADMIXTURE pipelines.

Related reading:

• What Tools Analyze Population Structure
• ADMIXTURE vs STRUCTURE: Choosing K & Validating Results
• IBD & ROH: What They Reveal About Your Cohort