Draft: work in progress. This recipe is not finished yet; sections may be incomplete and results may change.

Status: draft (2026-11-21), sections 1-4 written, results (sections 5-7) pending. Run with migrate-n 6.1.97.

Many data sets today are SNPs: RADseq, SNP chips, or the variable sites picked out of genome data. This recipe shows how to write SNP data for Migrate, which datatype and options to use, and how close SNP estimates come to estimates from the full sequences of the same loci. Read 00-basics and 01-migration first; 09-mutation-models section 5 has a first SNP example.

Contents

  1. The data and the true values
  2. Three ways to write the same SNPs
  3. The letter on the sites line decides the datatype
  4. Base frequencies and invariant sites
  5. Results: full sequences, linked SNPs, unlinked SNPs (pending)
  6. Run time: what makes SNP runs slow (pending)
  7. Recommendations (pending)

1. The data and the true values

Three populations in a stepping stone, West <-> Middle <-> East, with no direct migration between West and East. 100 unlinked loci of 1,000 sites, 8 sequences per population and locus, simulated with msprime under HKY (kappa 4, base frequencies A 0.3, C 0.2, G 0.2, T 0.3; scripts/simulate_snps.py, truth in data/truth.json):

ParameterTrue
Theta_West0.004
Theta_Middle0.002
Theta_East0.003
M Middle->West250
M West->Middle500
M East->Middle500
M Middle->East250

Theta x M is 1 for three routes and 0.75 for Middle->East. The 100 loci have 4,480 variable sites (14-123 per locus, mean 45).

2. Three ways to write the same SNPs

From the full sequences (data/full.txt, one (s1000) per locus) the script writes three SNP data sets:

FileSites lineWhat it is
data/linked.txt(n27) (n46) (n14) ...linked SNPs: the variable sites of each locus stay together, one locus per original locus
data/unlinked1.txt(n1) (n1) (n1) ... (100)unlinked SNPs: one random variable site per locus
data/unlinkedall.txt(n1) (n1) (n1) ... (4,480)every variable site as its own locus

The first two are correct descriptions of the data: SNPs within a locus share one genealogy, SNPs from different loci are independent. The third treats SNPs of the same locus as if they had independent genealogies; this is what one gets when every SNP of a RADseq or genome data set is entered as its own locus without checking linkage.

For many unlinked SNPs the sites line can be written compactly: a count in square brackets cuts the following locus into that many loci,

3 4480 every SNP its own locus
[4480](n4480)

is the same as 4,480 times (n1). The number of loci on the first line is the number after cutting (4480 here). Up to 6.1.97 and 7.0.121 it had to match (with 1, 6.1.97 crashed); later releases count the loci on the sites line and use that count. 10-loci-and-units section 6 has all the bracket forms.

3. The letter on the sites line decides the datatype

The letter in front of the number of sites, (s1000), (n27), (n1), sets the datatype of that locus: s sequence data, n SNP data. When all loci have the same letter, it overrides datatype= in the parmfile. Two consequences:

  • datatype=SNP in a parmfile does not mean SNP data: Migrate reads only the first letter, S, which is sequence data. The SNP datatype is datatype=NucleotidePolymorphismData (first letter N). With an infile whose loci are written (n...), the infile wins and the run is a SNP run anyway; with plain numbers or (s...) it is a sequence run.
  • To analyse the same SNPs as sequence data, the infile itself must say so: data/linked_s.txt, unlinked1_s.txt and unlinkedall_s.txt are the same data with (s...).

Older Migrate versions had a separate datatype for unlinked SNPs (datatype=UnlinkedSNPData, u, every column of a plain site count treated as its own locus). The (n1) loci and the [count] form above replace it; infiles with (u1) stop with an error in 6.1.97 and 7.0.121.

4. Base frequencies and invariant sites

Base frequencies. With freqs-from-data=YES Migrate counts the bases of every locus. For SNPs these counts come from the variable sites only, and for a one-site locus from a single column, so they say little about the frequencies of the sequence. The SNP runs here give the frequencies:

freqs-from-data=NO:0.3,0.2,0.2,0.3

(estimated once from all the data, or taken from a reference genome). One linked-SNP run uses freqs-from-data=YES to show the difference.

Invariant sites. SNP data lack the invariant sites, so Theta is per variable site and cannot be compared with Theta from sequences (09-mutation-models section 5). If the number of sites the SNPs were found in is known, it can be given after the frequencies:

freqs-from-data=NO:0.3,0.2,0.2,0.3 [1000]

Migrate then adds the invariant sites back (“Reconstituted Sequence data: SNPs + invariants sites” in the progress output), and Theta is per site again. The number is one value for all loci: the average number of sites per locus. Whether this works for unlinked SNPs (one SNP per locus of unknown length) is one of the questions of section 5.

The runs (all HKY with kappa 4, custom-migration={**0 *** 0**}, Theta prior uniform 0-1 for SNP runs and 0-0.02 for per-site runs, M prior uniform 0-2,000, heating=YES:1:POWER:5):

RunDataDatatypeBase frequencies
fullfull sequencessequencefrom data
linked-Slinked SNPssequencegiven
linked-N-datalinked SNPsSNPfrom data
linked-Nlinked SNPsSNPgiven
linked-N-totallinked SNPsSNP + 1,000 sites per locusgiven
unl1-Sone SNP per locussequencegiven
unl1-None SNP per locusSNPgiven
unlall-Severy SNP a locussequencegiven
unlall-Nevery SNP a locusSNPgiven

5. Results: full sequences, linked SNPs, unlinked SNPs

Pending (HPC runs of 2026-11-21).

6. Run time: what makes SNP runs slow

Pending.

7. Recommendations

Pending.

Available Materials