Skip to main content

Haplotype-based methods

Theme of this chapter

All of our exercises so far focused on population genetic statistics which are generally thought about in terms of allele frequencies and allele frequency correlations. However, one class of modeling tools implemented in slendr which are also extremely useful are methods based on haplotypes—i.e., continuous segments of DNA inherited from generation to generation while being broken up by the process of recombination.

To make this session a little more relaxed compared to previous exercises, this chapter presents these techniques as a set of “recipes” rather than extensive exercises. The primary goal is to conclude our exercise sessions with a few more tools before we switch gears and start implementing modeling workflows for your own projects or work through some of the few suggested case studies.

Preparation

Take a look at the following basic admixture model, and save it as haplotypes.R. Note also the presence of a small helper function I provided (you don’t have to study it, although it should look familiar if you’ve done the tidyverse and ggplot2 parts of this workbook):

##################################################
# simple admixture demographic model
library(slendr)
init_env()

popZ <- population("popZ", time = 3000, N = 500)
popX <- population("popX", time = 1500, N = 2000, parent = popZ)
popY <- population("popY", time = 1500, N = 10000, parent = popZ)

gf <- gene_flow(from = popX, to = popY, proportion = 0.2, start = 500, end = 499)

model <- compile_model(list(popZ, popX, popY), generation_time = 1, gene_flow = gf)

schedule <- rbind(
  schedule_recording(model, times = seq(1400, 0, by = -200), list(popY, 10)),
  schedule_recording(model, times = 0, list(popX, 10), list(popZ, 10))
)
  
ts <-
  msprime(model, sequence_length = 100e6, recombination_rate = 1e-8, schedule = schedule, random_seed = 42) %>%
  ts_mutate(mutation_rate = 1e-8, random_seed = 42)

samples <- ts_names(ts, split = TRUE)

##################################################
# a helper function to plot admixture tracts

library(ggplot2)
library(dplyr)
library(scales)

plot_tracts <- function(tracts, ind) {
  ind_tracts <- filter(tracts, name %in% ind) %>%
    mutate(chr = paste0(name, "\nchr. ", haplotype)) %>%
    mutate(chr = factor(chr, levels = unique(chr[order(node_id)])))

  ggplot(ind_tracts) +
    geom_rect(aes(xmin = left, xmax = right, ymin = 1, ymax = 2, fill = name),
              linewidth = 1) +
    labs(x = "coordinate along a chromosome [bp]") +
    theme_bw() +
    theme(legend.position = "none",
          axis.text.y = element_blank(), axis.ticks = element_blank(),
          panel.border = element_blank(), panel.grid = element_blank()) +
    facet_grid(chr ~ .) +
    scale_x_continuous(labels = comma)
}

Here is what this model look like. Note particularly the “ancient DNA time series” we simulated in popY and the admixture from popX into popY:

plot_model(model, schedule = schedule, proportions = TRUE)

Exercise: Local ancestry inference (LAI) with ts_tracts()

As mentioned above, we’ve learned a lot about admixture tests based on allele frequency correlations, namely \(f\)-statistics. Although very powerful, there are situations where they either lose inference power or they don’t allow us to answer deeper questions we might be also interested in.

For instance, what if we want to detect not only if or how much admixture happened, but where in the genome can we detect continuous admixture blocks?

A wide range of software methods called Local Ancestry Inference (LAI) have been developed do do exactly this, each with their strengths and weaknesses. For an overview, see this preprint which I put together with a former PhD student about LAI methods (fun fact: slendr is what made this work possible!).

On the simulation side, slendr provides a function ts_tracts(), which can extract the exact coordinates of admixture tracts resulting an admixture event. This is extremely useful both for simulation-based inference, but also for benchmarking software methods, picking which method gives the most accurate answer in our scenario of interest, etc.


If you have a simulated tree sequence ts (such as the one simulated by your script haplotypes.R), you can obtain admixture tracts by providing a so-called “census time” to the function ts_tracts() (this is a slightly strange name for a low-level technical concept corresponding to the time of gene-flow we want to focus on). In case of our model, set this census to 500 generations and add the following command to your script haplotypes.R, then run it. What’s the format of the data it gives you? Can you guess what sort of information it contains by looking through it?

tracts <- ts_tracts(ts, census = 500)

When you look at the output of this function, you seen that it’s a plain data frame with many columns which will be familiar to you:

head(tracts)
# A tibble: 6 × 10
  name    haplotype  time pop   source_pop     left   right length source_pop_id
  <chr>       <int> <dbl> <chr> <fct>         <dbl>   <dbl>  <dbl>         <dbl>
1 popY_51         1   400 popY  popX        3203460  6.14e6 2.94e6             1
2 popY_51         1   400 popY  popX        6463080  8.31e6 1.84e6             1
3 popY_51         1   400 popY  popX       11598709  1.28e7 1.15e6             1
4 popY_51         1   400 popY  popX       23655661  2.38e7 1.16e5             1
5 popY_51         1   400 popY  popX       26049625  2.72e7 1.15e6             1
6 popY_51         1   400 popY  popX       40089367  4.57e7 5.56e6             1
# ℹ 1 more variable: node_id <dbl>

For instance, name indicates the name of the individual carrying a given admixture tract derived from admixture from source population source_pop with genomic coordinates between left and right.


Can you guess the meaning of the haplotype column? How many of them are there for any given individual? You can use your tidyverse magic to answer this.

This finds the haplotype number and node ID for each individual:

tracts %>% group_by(name) %>% distinct(haplotype, node_id)
# A tibble: 60 × 3
# Groups:   name [30]
   name    haplotype node_id
   <chr>       <int>   <dbl>
 1 popY_51         1     100
 2 popY_51         2     101
 3 popY_52         1     102
 4 popY_52         2     103
 5 popY_53         1     104
 6 popY_53         2     105
 7 popY_54         1     106
 8 popY_54         2     107
 9 popY_55         1     108
10 popY_55         2     109
# ℹ 50 more rows

Haplotype is basically equivalent to “chromosome” in this case. Because each simulated slendr individual is diploid, we get one “chromosome” for each of them. The node_id column is a low-level numerical identifier for such chromosome used by the underlying tskit Python module which handles tree-sequence operations.

Here are both columns for the couple of individuals separately, making it clear that there are always two entries for each of them:

tracts %>% group_by(name)  %>% filter(name == "popY_71") %>% distinct(haplotype, node_id)
# A tibble: 2 × 3
# Groups:   name [1]
  name    haplotype node_id
  <chr>       <int>   <dbl>
1 popY_71         1     160
2 popY_71         2     161
tracts %>% group_by(name)  %>% filter(name == "popY_80") %>% distinct(haplotype, node_id)
# A tibble: 2 × 3
# Groups:   name [1]
  name    haplotype node_id
  <chr>       <int>   <dbl>
1 popY_80         1     178
2 popY_80         2     179

In the script above, I provided the function plot_tracts() for you. The way it works is that you give it a table of all tracts and the names of some individuals recorded in the tree sequence.

You can probably guess what this function does. To test this function, give it the simulated tracts data frame and a vector of names of individuals who span a wider range of “aDNA time points”, starting from the oldest individual and ending by an individual “from the present day” (but no more than one individual from each time point, just to keep things manageable).

What do you see in terms of the number of tracts and the length of tracts across these individuals? Can you detect some distinctive pattern or differences between the individual tracts (even just visually, we’ll do this more rigorously later)?

Let’s apply some tidyverse table munging to select individuals of different times(remember, we recorded oldest individuals at 1000 generations ago, the youngest individuals at 0 generations ago). Of course, you could also do this manually, but this is more effective, particularly if we needed to subsample many individuals.

names <- tracts %>% group_by(time) %>% distinct(name) %>% slice_sample(n = 1) %>% pull(name)
names
[1] "popY_76" "popY_69" "popY_51"

We then simply provide these names to the helper function:

plot_tracts(tracts, names)

It looks like the older individual is, the closer they lived to the start of the admixture event, and the longer the tracts they carry will be. Which makes perfect sense!


If we were interested in benchmarking some inference methods (all of which produce data very similar to the tracts table), this is the ground truth we would be comparing its performance against—effectively the results of “the perfect method” which never makes a mistake.

We’ll give a tip on how to do this benchmarking in practice in the final exercise of this chapter.

Exercise: Dating admixture events

Once we have a set of admixture tracts (either simulated or inferred empirically), we can try to date the admixture event. Again, we simulated our tracts and so we know this admixture date exactly, of course. But that’s not the point here. Typically what we want to do is to simulate genomic data (see the final exercise) from our model, and then use this data as an input to external inference software to ask the question: How well can this software infer the truth? An example of such software is DATES, MOSAIC, or FLARE.

Still, let’s do a little theoretical exercise to demonstrate how admixture tract coordinates can be used to infer admixture times. In fact, this is not far from how the methods mentioned above actually do this, so it’s quite useful to know even besides intellectual curiosity.


First, compute the average length of a ancestry tracts in individuals recorded in each time point, then visualize the length distribution of these tracts stratified by their length (i.e., assign a color to each distribution).

Hint: You only need a little bit of tidyverse and ggplot2 knowledge to do this. Take a look at the relevant chapters on the left if you need a refresher. We did something similar with our example IBD data set.

Let’s compute the average length in each time bin:

tracts %>%
  group_by(time) %>%
  summarise(mean(length))
# A tibble: 3 × 2
   time `mean(length)`
  <dbl>          <dbl>
1     0        247912.
2   200        398617.
3   400       1153801.

Obviously, we can see that the older the individual, the closer to the admixture event that individual is and, consequently, the longer the admixture tracts are. This is, of course, because recombination hadn’t yet had the time to break up longer admixture chunks into shorter pieces.

We can get a better idea about this by plotting the admixture tract length distributions like this:

ggplot(tracts, aes(length, color = factor(time))) +
  geom_density() +
  coord_cartesian(xlim = c(0, 3e6)) +
  theme_bw() +
  scale_color_discrete("Time of\nrecording") +
  labs(title = "Distribution of admixture lengths, stratified by age group",
       x = "admixture tract length [bp]")


Suppose we only have sequences of present-day individuals. In our script, let’s subset the tracts data frame to only individuals recorded at time 0 (“the present day”):

tracts <- filter(tracts, time == 0)

When we look again at the distribution of tracts lengths observed in individuals at time 0 a bit more carefully, we can notice that it seems to follow the exponential distribution:

Exponential distribution is governed by the following density function with a rate parameter \(\lambda\):

\[ f(\textrm{tract length }~x) \sim \lambda \exp^{-\lambda x} \]

In the case of exponential decay of admixture tracts and after making some simplifying assumptions, the \(\lambda\) rate parameter can be parametrized as:

\[ \lambda = \frac{1}{r t}, \] where \(r\) is the recombination rate and \(t\) is the time (in generations) since the admixture event.

The expected value of such exponential distribution is given by:

\[ \mathop{\mathbb{E}} [X] = \frac{1}{\lambda} \]

Because we can get the maximum likelihood value of this expected average simply by computing a simple mean of tract lengths \(\bar{x}\), we can also write:

\[ \bar{x} \approx \mathop{\mathbb{E}} [X] = \frac{1}{\lambda}. \]

Simply by rearranging this equation, we can therefore get an estimate the rate of exponential decay \(\hat{\lambda}\) of the underlying exponential distribution of the tract lengths as:

\[ \hat{\lambda} = \frac{1}{\bar{x}}. \]

We can also verify our assumptions by overlaying a theoretical exponential distribution density corresponding to the tract length data. (This is a very technical bit, so feel free to skip this):

We can do this using the dexp() function:

But more importantly, because we know that \(\lambda = 1 / (r t)\), assuming we know the uniform average recombination rate \(r\) reasonably well, we can estimate the time of admixture simply by rearranging this equation to extract the admixture time \(t\) as:

\[ t \approx \frac{\hat{\lambda}}{r} \]

For example, given a vector of tract lengths in our simulated individuals “from the present day”:

head(tracts$length, 10) # ... etc
 [1] 171668  16025 413619  97932  87025 807168  48615  96072  33498  77603

we can estimate the rate of exponential decay \(\hat{\lambda}\) like this:

lambda_hat <- 1 / mean(tracts$length)
lambda_hat
[1] 4.033696e-06

and then use this value to estimate of time since admixture in the history of these individual directly:

r <- 1e-8 # recombination rate (crossovers per bp per generation)

admixture_time <- lambda_hat / r # admixture time in "generations before this individual lived"

admixture_time
[1] 403.3696

You can see that we’re a little bit of from the true value of 500 generations (after all, we only simulated a small part of the genome), but still, hopefully this gives you a hint of how admixture dating methods work, at least in principle.

Real-world inference uses mathematical machinery which is a little bit more sophisticated (usually we deal with filtered tracts, or we don’t even have full haplotypes and can only work with linkage information between individual alleles), but the general ideas remains the same—fitting an exponential curve to the information signal left in admixed genomes by the process of recombination.

Exercise: Identity-by-Descent segments (IBD)

Another function useful for studying demographic history using haplotypes is ts_ibd(). As the name suggests, this function extracts IBD segments for the given set of individuals recorded in a tree sequence.

Let’s first get the names of individuals “at the present”:

samples <- ts_recorded(ts) %>% filter(time == 0)
samples
# A tibble: 30 × 3
   name     time pop  
   <chr>   <dbl> <chr>
 1 popX_1      0 popX 
 2 popX_2      0 popX 
 3 popX_3      0 popX 
 4 popX_4      0 popX 
 5 popX_5      0 popX 
 6 popX_6      0 popX 
 7 popX_7      0 popX 
 8 popX_8      0 popX 
 9 popX_9      0 popX 
10 popX_10     0 popX 
# ℹ 20 more rows

In general, there are two modes of operation for the ts_ibd() function (depending on whether we set its argument within or between) as outlined bellow.

(Additionally, because the IBD data from even a tiny simulation can be absolutely huge, we typically need to pre-filter which IBDs to extract, for instance by setting the maximum_time argument, which only searches for IBDs that aren’t resulting from a most recent common ancestor (MRCA) not older than the given time. Alternatively, we also have the option to filter for minimum_length, but see the instructions in ?ts_ibd for some caveats.)

  1. We can look for IBD segments within a given group of individuals by providing the names of the group of individuals within which to extract IBD segments.
ibd_within <- ts_ibd(ts, within = samples$name, maximum_time = 100)

Looking at the data, we see a familiar data frame structure again, namely with pairs of names of two individuals name1 and name2 for each IBD segment (each row of the data frame), the time tmrca of the most common ancestor from which the IBD segment was inherited.

When we summarize how many segments of what average length do we find in our simulated sample set (a simple metric of relatedness), we can see that the amount of IBDs follows the \(N_e\) of the population in our model: the smaller the \(N_e\), the more related (and with more IBD) we observe in our populations:

ibd_within %>%
  group_by(pop1, pop2) %>%
  summarize(ibd_count = n(), ibd_length = mean(length))
# A tibble: 3 × 4
# Groups:   pop1 [3]
  pop1  pop2  ibd_count ibd_length
  <fct> <fct>     <int>      <dbl>
1 popZ  popZ       1540   1112047.
2 popX  popX        513   1325700.
3 popY  popY         92    965703.
plot_model(model, proportions = TRUE)

  1. We can look for IBD segments between two groups by providing two sets of individuals.

Let’s first convert our present-day only table of samples into the necessary format (list of vectors, as we discussed many times before).

samples <- split(samples$name, samples$pop)
samples
$popX
 [1] "popX_1"  "popX_2"  "popX_3"  "popX_4"  "popX_5"  "popX_6"  "popX_7" 
 [8] "popX_8"  "popX_9"  "popX_10"

$popY
 [1] "popY_71" "popY_72" "popY_73" "popY_74" "popY_75" "popY_76" "popY_77"
 [8] "popY_78" "popY_79" "popY_80"

$popZ
 [1] "popZ_1"  "popZ_2"  "popZ_3"  "popZ_4"  "popZ_5"  "popZ_6"  "popZ_7" 
 [8] "popZ_8"  "popZ_9"  "popZ_10"

Let’s run ts_ibd() with the between mode. Notice that we see nothing between any pair of the three populations if we keep the maximum_time = 100 filter present. This makes sense because the splits between the populations (and their \(N_e\)) don’t allow for such “young” IBD segments to persist. This applies also to the popY-popX pair whose demographic history involves a substantial gene flow event of 20%!

ts_ibd(ts, between = samples[c("popZ", "popX")], maximum_time = 100)
[1] node1 node2 mrca  tmrca left  right
<0 rows> (or 0-length row.names)
ts_ibd(ts, between = samples[c("popZ", "popY")], maximum_time = 100)
[1] node1 node2 mrca  tmrca left  right
<0 rows> (or 0-length row.names)
ts_ibd(ts, between = samples[c("popY", "popX")], maximum_time = 100)
[1] node1 node2 mrca  tmrca left  right
<0 rows> (or 0-length row.names)

We see the same thing between the popY-popX pair even when we filter for IBD segments inherited right at the time the gene-flow ended (obviously):

ts_ibd(ts, between = samples[c("popY", "popX")], maximum_time = 499)
[1] node1 node2 mrca  tmrca left  right
<0 rows> (or 0-length row.names)

Finally, we do pick up an admixture signal when we allow IBD segments tracing the MRCA between the two populations to the exact generation during which the admixture began:

ts_ibd(ts, between = samples[c("popY", "popX")], maximum_time = 500)
# A tibble: 10 × 13
   node1 node2 length  mrca node1_time node2_time tmrca     left    right name1 
   <int> <int>  <dbl> <dbl>      <dbl>      <dbl> <dbl>    <dbl>    <dbl> <chr> 
 1   142   178 156916  7917          0          0  499. 54401344 54558260 popX_2
 2   144   172  25925  7931          0          0  500. 53903357 53929282 popX_3
 3   144   178 243159  7917          0          0  499. 54315101 54558260 popX_3
 4   145   172  25925  7931          0          0  500. 53903357 53929282 popX_3
 5   145   178   8468  7917          0          0  499. 54524139 54532607 popX_3
 6   148   178 138802  7917          0          0  499. 54315101 54453903 popX_5
 7   150   178  83307  7917          0          0  499. 54412132 54495439 popX_6
 8   151   178 138802  7917          0          0  499. 54315101 54453903 popX_6
 9   156   178 138802  7917          0          0  499. 54315101 54453903 popX_9
10   158   178 138802  7917          0          0  499. 54315101 54453903 popX_…
# ℹ 3 more variables: name2 <chr>, pop1 <fct>, pop2 <fct>

Unlike every single statistical method introduced in this workshop, there’s a caveat to using ts_ibd() used for real-world simulation-based inference of demographic history or software benchmarking, and it has to do with an issue in how the underlying tskit tree-sequence machinery handles IBD segments. Read the linked GitHub issue as well as my note in the ?ts_ibd help page to learn more.

That said, if you want to do real-world inference using IBD segments on real data, this would anyway require applying third-party software doing the inference anyway (AncIBD, IBDSeq, Ibis, etc.). For this reason, this issue doesn’t have much practical implication.

For those applications, let’s move on to how you’d go about approaching tying slendr simulations with external software.

Bonus exercise: Converting tree sequences to other genotype formats

As convenient as it is to always work in R with user-friendly modeling interface of slendr, it’s library of tskit tree-sequence statistical functions, and the whole tidyverse and ggplot2 data science packages, real-world research requires using third-party external software. In general, software like this doesn’t work with tree-sequence data structures, and even when it does, our real-world data doesn’t come in the form of tree sequences—it takes the form of genotype files such as VCF, EIGENSTRAT, PLINK, and others.

Luckily, slendr provides convenient means to convert tree sequences into standard genotype formats. For instance, if we have a tree sequence object ts, we can:

  1. Obtain a VCF file with the function ts_vcf()
ts_vcf(ts, path = "/tmp/genotypes.vcf.gz")
bcftools view -s popX_1,popY_1,popZ_1 /tmp/genotypes.vcf.gz | head -n15
##fileformat=VCFv4.2
##FILTER=<ID=PASS,Description="All filters passed">
##source=tskit 1.0.2
##contig=<ID=chr1,length=1000000>
##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
##INFO=<ID=AC,Number=A,Type=Integer,Description="Allele count in genotypes">
##INFO=<ID=AN,Number=1,Type=Integer,Description="Total number of alleles in called genotypes">
##bcftools_viewVersion=1.25+htslib-1.25
##bcftools_viewCommand=view -s popX_1,popY_1,popZ_1 /tmp/genotypes.vcf.gz; Date=Fri Nov 13 18:19:59 2026
#CHROM  POS ID  REF ALT QUAL    FILTER  INFO    FORMAT  popX_1  popY_1  popZ_1
chr1    63  0   A   T   .   PASS    AC=0;AN=6   GT  0|0 0|0 0|0
chr1    177 1   A   C   .   PASS    AC=0;AN=6   GT  0|0 0|0 0|0
chr1    910 2   C   G   .   PASS    AC=0;AN=6   GT  0|0 0|0 0|0
chr1    3112    3   G   C   .   PASS    AC=0;AN=6   GT  0|0 0|0 0|0
chr1    3288    4   G   A   .   PASS    AC=0;AN=6   GT  0|0 0|0 0|0
  1. Convert our data into the EIGENSTRAT trio of files for ADMIXTOOLS with the function ts_eigenstrat()
ts_eigenstrat(ts, prefix = "/tmp/eigenstrat")
2 multiallelic sites (0.180% out of 1111 total) detected and removed
EIGENSTRAT object
=================
components:
  ind file: /tmp/eigenstrat.ind
  snp file: /tmp/eigenstrat.snp
  geno file: /tmp/eigenstrat.geno
  1. Get a normal table of genotypes as a data frame with the function ts_genotypes()
ts_genotypes(ts)
2 multiallelic sites (0.180% out of 1111 total) detected and removed
# A tibble: 1,109 × 201
     pos popY_1_chr1 popY_1_chr2 popY_2_chr1 popY_2_chr2 popY_3_chr1 popY_3_chr2
   <int>       <int>       <int>       <int>       <int>       <int>       <int>
 1    63           0           0           0           0           0           0
 2   177           0           0           0           0           0           0
 3   910           0           0           0           0           0           0
 4  3112           0           0           0           0           0           0
 5  3288           0           0           0           0           0           0
 6  4667           0           0           0           0           0           0
 7  6010           0           0           0           0           0           0
 8  8962           0           0           0           0           0           0
 9  9380           0           0           0           0           0           0
10 10303           0           0           0           0           0           0
# ℹ 1,099 more rows
# ℹ 194 more variables: popY_4_chr1 <int>, popY_4_chr2 <int>,
#   popY_5_chr1 <int>, popY_5_chr2 <int>, popY_6_chr1 <int>, popY_6_chr2 <int>,
#   popY_7_chr1 <int>, popY_7_chr2 <int>, popY_8_chr1 <int>, popY_8_chr2 <int>,
#   popY_9_chr1 <int>, popY_9_chr2 <int>, popY_10_chr1 <int>,
#   popY_10_chr2 <int>, popY_11_chr1 <int>, popY_11_chr2 <int>,
#   popY_12_chr1 <int>, popY_12_chr2 <int>, popY_13_chr1 <int>, …

With these three functions, you can always finish your slendr simulation scripts with a file conversion to another fileformat and pick up your inference work in a different third-party software (IBDseq, DATES, ADMIXTOOLS, PLINK, etc.).