bio-ecological-genomics-landscape-genomics

What this skill does

## Version Compatibility

Reference examples tested with: LEA 3.14+ (lfmm2 via LEA 3), pcadapt 4.3+, OutFLANK 0.2+, vegan 2.6+, gradientForest 0.1-32+, terra 1.7+, qvalue 2.34+, BayPass 2.3+

Before using code patterns, verify installed versions match. If versions differ:
- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters
- CLI: `<tool> --version` then `<tool> --help` to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.

# Landscape Genomics

**"Find loci associated with environmental adaptation in my populations"** -> Genotype-environment association with K-selected latent-factor correction, multivariate RDA for polygenic signal, paired with demography-calibrated FST outliers; genomic-offset prediction with explicit prediction-novelty regime characterization.
- R: `LEA::lfmm2()` (modern; via LEA 3) for univariate GEA with cross-entropy-elbow K choice
- R: `vegan::rda()` with `Condition()` for partial-RDA polygenic GEA
- R: `OutFLANK::OutFLANK()` for demography-calibrated FST outliers
- R: `pcadapt::pcadapt()` for PC-based scans without environmental data
- CLI: `g_baypass` for BayPass Bayesian Core/AUX/C2/IS analyses

## The Single Most Important Modern Insight -- GEA is a Four-Confound Problem, Not a Signal-Plus-Noise Problem

The number-one failure mode in landscape genomics is treating "is locus X associated with environment Y" as a simple signal-extraction problem (the NimBios working group consolidated this view in Hoban 2016 *Am Nat* 188:379-397). **GEA has FOUR concurrent confounds**:
1. **Population structure** — IBD-driven allele-frequency gradients track distance, which correlates with most environmental variables
2. **Demographic history** — range expansion creates allele-frequency clines along the expansion axis that mimic selection (Lotterhos & Whitlock 2014 *Mol Ecol* 23:2178-2192)
3. **Background and linked selection** — reduces diversity in low-recombination regions, inflating apparent local-FST signals
4. **Sampling design** — non-random spatial sampling creates spurious GEA signals (Lotterhos & Whitlock 2015 *Mol Ecol* 24:1031-1046; **paired contrasts > random > transects** when demography is concerning)

A second cornerstone: **Forester et al. 2018 established RDA as the best polygenic-adaptation detector** but with a caveat — RDA performance requires imputed genotypes (no missing data) and is best for linear-gradient environments. For monogenic strong-selection loci, OutFLANK and BayPass-C2 remain competitive.

A third: **Genomic offset has three regimes** (Lind & Lotterhos 2025 *Mol Ecol Resour* 25:e14008): works well for interpolation (similar-to-training environments), degrades gracefully for modest extrapolation, FAILS for highly novel future environments. Reporting a single offset map without characterizing prediction-novelty is methodologically incomplete. For the broader eco-evolutionary integration framework, see Aguirre-Liguori 2021 *Nat Ecol Evol* 5:1350-1360.

## Algorithmic Taxonomy

| Method | Type | Strength | Fails when |
|--------|------|----------|------------|
| FST outliers (naive) | Univariate per-locus | Simple; widely understood | Inflated FDR under demography (Lotterhos & Whitlock 2014) |
| OutFLANK (Whitlock & Lotterhos 2015) | Univariate FST with trimmed null | Robust to demography via trimmed-tail null | Conservative; misses weak-effect polygenic |
| pcadapt (Luu 2017) | PC-based Mahalanobis | Handles continuous structure; no need to define populations | Detects axes-of-divergence loci; not environment-specific |
| LFMM (Frichot 2013) | MCMC mixed model with latent factors | Original framework | Slow; superseded by LFMM2 |
| LFMM2 (Caye 2019) | LSE-based mixed model with K latent factors | Fast; orders of magnitude faster than LFMM; modern default | K choice is critical; wrong K silently invalidates results |
| BayPass Core (Gautier 2015) | Bayesian FST with covariance matrix Omega | Explicit shared-history correction via Omega | Computationally heavy; convergence needs care |
| BayPass AUX | Bayesian env association with binary auxiliary variable | Posterior gives Bayes Factor per locus | Same as Core |
| BayPass C2 | Bayesian contrast between two pre-defined groups | Like Bayesian Fisher exact | Requires pre-defined groups, not continuous env |
| BayPass IS | Importance-sampling joint Bayesian | Multiple covariates simultaneously | Most computationally expensive |
| RDA (Forester 2018) | Multivariate constrained ordination | HIGH power and LOW FDR for polygenic adaptation | Requires imputed genotypes; less power for monogenic |
| pRDA (partial RDA) | RDA conditioning out population structure | Controls for structure explicitly | Conservative; depends on which axes are conditioned out |
| Gradient forests (Ellis 2012; Ellis-Smith-Pitcher) | Random-forest non-linear GEA | Detects non-linear gene-environment | Less interpretable; no formal p-values |
| RDA offset (Capblancq 2021) | Linear genomic-offset prediction | Linear gradient assumption | Fails under highly novel future climate (Lind 2025) |
| Gradient-forest offset | Non-linear genomic-offset prediction | Captures non-linearity | Same three-regime caveat |
| RONA | Locus-by-locus offset | Simple, transparent | Locus-specific; ignores multilocus structure |
| Circuitscape (McRae 2008) | Circuit-theory landscape resistance | Integrates ALL paths; not single-best | Symmetric only; asymmetric landscapes need directional methods |
| ResistanceGA (Peterman 2018) | Genetic-algorithm optimization of resistance | Optimizes cost surface itself | MLPE parameterization needed (specific lmer form) |

## Decision Tree by Scenario

| Scenario | Recommended approach | Why |
|----------|---------------------|-----|
| Monogenic local adaptation | OutFLANK or BayPass Core; cross-check with simulations | Demography-calibrated null |
| Polygenic local adaptation | RDA with environmental matrix; pRDA conditioning on structure | Forester 2018 superior power + lower FDR |
| Environmental association with structure correction | LFMM2 (K from sNMF cross-entropy elbow) | Modern default; orders of magnitude faster than LFMM |
| Binary group contrast | BayPass C2 | Like Bayesian Fisher exact |
| Joint multi-covariate Bayesian inference | BayPass IS | Multiple env simultaneously |
| Quantifying maladaptation under climate change | RDA offset OR gradientForest offset | Report Lind 2025 caveat: works for interpolation, fails for novel |
| Multi-method consensus | Run OutFLANK + LFMM2 + BayPass; overlap is high-confidence | Method differences = methodological coverage |
| Mapping landscape resistance | Circuitscape + ResistanceGA optimization | Circuitscape integrates all paths; ResistanceGA optimizes the surface |
| Distinguishing IBD vs IBE | dbRDA variance partitioning (geographic + env) | Mantel-based methods have known autocorrelation issues |
| Sampling design optimization | Paired contrasts at environmental endpoints; cite Lotterhos & Whitlock 2015 | Most powerful under demographic concern |
| Polyploid species | polyRAD / fitPoly / updog FIRST; then standard GEA | Diploid-assuming tools give biased FST estimates |

## LFMM2 with Mandatory K Selection

**Goal:** Identify loci significantly associated with environmental variables while controlling for unobserved demographic structure via K latent factors.

**Approach:** Run sNMF on the genotype matrix across K = 1...10 (or higher), compute cross-entropy at each K, pick K at the elbow (where cross-entropy first plateaus), then pass that K to `LEA::lfmm2()`. Wrong K silently invalidates results — too few K means residual structure confounds environment; too many K absorbs the environmental signal.

```r
library(LEA)
library(qvalue)

# Convert VCF -> LFMM/GENO format
vcf2lfmm('variants.vcf', 'genotypes.lfmm')
vcf2geno('variants.vcf', 'genotypes.geno')

# MANDATORY K selection via