IdentityByDescentDispersal.jl: Spatial Demography Inference

• IdentityByDescentDispersal.jl is a Julia package for inferring effective dispersal rates and population density from the spatial distribution of IBD blocks.
• The package implements a composite likelihood framework that combines diffusion-based models with numerical integration, enabling flexible demographic parameter estimation.
• It supports end-to-end workflows—from simulation and IBD block detection to AD-compatible Bayesian and maximum-likelihood inference—for spatial genomic data.

Searching arXiv for the package paper and closely related IBD/dispersal work. Searching arXiv for IdentityByDescentDispersal.jl and related IBD/dispersal papers. IdentityByDescentDispersal.jl is a Julia package for inferring two central spatial-demographic parameters from genomic data: the effective dispersal rate and the effective population density. It does this using the spatial distribution of identity-by-descent (IBD) blocks shared between sampled individuals. An IBD block is defined as a segment of DNA that has been inherited by a pair of individuals from a common ancestor without being broken by recombination. The package is a practical software implementation of the inference framework introduced by Ringbauer, Coop, and Barton (2017), with extensions that make the method more flexible and computationally efficient in practice (Jiménez et al., 9 Jul 2025).

1. Biological and inferential setting

In continuously distributed populations, nearby individuals tend to share more recent ancestry than distant individuals. If one can detect long chromosomal segments inherited from a recent common ancestor without intervening recombination, then the abundance of those segments, their lengths, and how often they occur between individuals at different geographic distances together contain information about recent movement and local effective density (Jiménez et al., 9 Jul 2025). Long IBD blocks usually indicate recent common ancestry, because recombination breaks ancestral chromosomes into progressively shorter pieces as time passes. Thus block length acts as a rough clock: longer blocks correspond to more recent coalescent events.

Spatial separation adds a second axis of information. If recent common ancestry is observed even at large geographic distances, that implies greater dispersal; if IBD sharing decays rapidly with distance, that implies more localized movement and/or higher density. The method therefore leverages a direct connection between recent coalescent events in space and observed IBD sharing (Jiménez et al., 9 Jul 2025).

The package is intended for settings in which georeferenced genomic samples are available, IBD segments can be detected between individuals, and recent dispersal and effective density are the primary inferential targets. The paper identifies conservation biology, fragmented populations, invasive species, and evolutionary studies of contemporary gene flow as especially suitable applications. Because IBD blocks reflect recent shared ancestry, the method targets recent demographic processes more directly than many allele-frequency-based methods (Jiménez et al., 9 Jul 2025).

A broader theoretical context is that recent coalescence in continuous space is often approximated by diffusion-based models of ancestral movement. A mathematically explicit justification for effective-size replacement at large spatial scales in two dimensions is provided by work on logistic branching random walks, which shows that genealogical behavior at large sampling distances agrees with classical continuous-space isolation-by-distance asymptotics (Birkner et al., 2024). This suggests that the package’s use of effective local density is aligned with a wider theoretical program rather than being a purely ad hoc parametrization.

2. Core mathematical framework

The package models the expected density of shared IBD blocks between two individuals at distance $r$, for blocks of length $L$, under a demographic model parameterized by dispersal rate and effective density through time. The central expression is

$$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$

where $G$ is genome length in Morgans, $t$ is time in generations before present, $L$ is block length in Morgans, $r$ is present-day geographic distance between the pair, and $\Phi(t \mid r, \theta)$ is the instantaneous coalescence rate at time $t$ for two homologous loci that are initially $r$ apart under demographic parameters $L$0 (Jiménez et al., 9 Jul 2025). The default implementation uses a slightly more complicated version that accounts for chromosome edges and diploidy, but this is the central formula.

Its interpretation is explicit in the paper. The coalescence term $L$1 describes how likely the two lineages are to coalesce at time $L$2 given spatial separation and demography. The factor $L$3 comes from recombination: the probability that a segment survives unbroken over $L$4 generations decreases exponentially with both block length and time. The $L$5 term is the recombination-related factor counting opportunities for a block of length $L$6 to be delimited by recombination breakpoints around the ancestral tract (Jiménez et al., 9 Jul 2025).

The scientific basis follows Ringbauer et al. (2017), which used a diffusion approximation for dispersal in continuous space. Under that approximation, lineages traced backward in time spread as a Gaussian random walk with variance determined by the per-generation dispersal parameter $L$7. Coalescence happens when lineages come sufficiently close, with rate inversely related to local effective population density. The key assumptions are therefore continuous-space diffusion-based dispersal, recombination approximately Poisson along the genetic map, and a coalescence approximation linking local encounter probability of lineages to effective density (Jiménez et al., 9 Jul 2025).

The package supports three parameterizations of the effective population density function $L$8:

Suffix	Density model	Solution mode
constant_density	$L$9	solved analytically
power_density	$$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$0	solved analytically
custom	user-defined $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$1	solved numerically

For the first two, the relevant expressions are available analytically; for arbitrary density histories, the package evaluates the integral numerically (Jiménez et al., 9 Jul 2025).

3. Statistical inference and computation

The statistical layer uses a composite likelihood. The observed number of IBD blocks in a small length bin $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$2 for a pair of individuals at distance $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$3 is assumed to follow a Poisson distribution with mean

$$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$4

From the stated model, the contribution for count $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$5 in a bin is the usual Poisson log-likelihood,

$$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$6

summed over bins and pairs (Jiménez et al., 9 Jul 2025). It is called a composite likelihood because independence between all observations is not literally true: blocks within genomes and across pairs are not fully independent.

A major software contribution is that the package generalizes Ringbauer et al.’s original analytically tractable family $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$7 to arbitrary effective density histories. It does so by numerically evaluating the relevant integrals using Gaussian quadrature rules, specifically via QuadGK.jl (Johnson 2013) (Jiménez et al., 9 Jul 2025). This allows custom demographic scenarios rather than restriction to constant or power-law density change.

The paper emphasizes that the package is fully compatible with automatic differentiation, including differentiation with respect to $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$8. This is a practical improvement over the original implementation strategy in Ringbauer et al., where the authors used gradient-free optimization. Because the composite likelihood is AD-compatible, the package can plug into standard gradient-based optimizers and modern Bayesian samplers in the Julia ecosystem (Jiménez et al., 9 Jul 2025).

The design is organized around two main sets of functions. The expected_ibd_blocks* functions compute the expected density of IBD blocks per pair of individuals and per unit of block length under a specified demographic model. The composite_loglikelihood* functions compute the composite likelihood of observed data given model parameters. The paper also mentions a maximum_likelihood interface for computing MLEs, and Bayesian inference through frameworks such as Turing.jl by directly injecting the composite log-likelihood into a probabilistic model. Because the likelihood is AD-compatible, one can use gradient-based samplers such as NUTS and standard gradient-based optimization routines. Confidence intervals in the MLE workflow are computed from the Fisher information matrix (Jiménez et al., 9 Jul 2025).

This computational orientation places the package within a wider trend in IBD-based inference toward explicit tract-length modeling and reusable likelihood components. Related analytical work on IBD tracts and ROH also emphasizes that tract lengths are naturally linked to broad age kernels rather than to single-generation timestamps, and that numerical integration or summation over those kernels is often the right computational abstraction (Santiago, 5 May 2026).

4. Software organization and end-to-end workflow

IdentityByDescentDispersal.jl is not limited to the theoretical core. The repository includes a simulation template in SLiM for forward-time simulation in continuous space with tree-sequence recording, intended for checking assumptions, calibration, and benchmarking. It also includes a Snakemake bioinformatics pipeline from phased VCF files to IBD-based inference (Jiménez et al., 9 Jul 2025).

The Snakemake pipeline takes as input phased VCF files, corresponding genetic maps, and a CSV file of pairwise geographic distances between individuals. It then detects IBD blocks using HapIBD, post-processes them with Refined IBD, and outputs a CSV compatible with the package’s preprocess_dataset function (Jiménez et al., 9 Jul 2025). This establishes a concrete path from raw genotype data to parameter estimates.

The workflow described in the paper is therefore end-to-end: simulation, preprocessing, theoretical expectation calculation, likelihood evaluation, and either maximum-likelihood or Bayesian inference. A plausible implication is that the package is designed as a methodological bridge between population-genetic theory and empirical genomics rather than as an isolated numerical library.

The preprocessing emphasis also exposes a practical boundary of the method. IdentityByDescentDispersal.jl relies on inferred IBD blocks, not directly on the latent genealogical process. This means the accuracy of the inferential output is coupled to IBD calling performance. That dependency is not unique to this package; it is a general feature of tract-based inference. Work on conflation of short IBD segments shows that many inferred short segments, especially in the $$\mathbb{E}[N_L \mid r, \theta] = \int_0^\infty G4t^2 \exp(-2Lt) \cdot \Phi(t \mid r, \theta) \,dt$$9–$G$0 cM range, may be composite rather than single uninterrupted tracts, which can bias downstream analyses based on tract-length distributions (Chiang et al., 2014).

5. Example analysis and reported performance

The paper illustrates Bayesian and maximum-likelihood usage on simulated, error-free IBD blocks from 100 diploid individuals sampled from a constant-density population. The true parameters were approximately

$G$1

Using the composite likelihood within Turing.jl and NUTS, the pseudo-posterior concentrated near the true values:

$G$2

The MLE analysis gave

$G$3

with 95% CI 260–303, and

$G$4

with 95% CI 0.065–0.071 (Jiménez et al., 9 Jul 2025).

These results show that, in a synthetic setting matching model assumptions and without IBD detection error, the package can recover the true recent spatial-demographic parameters accurately. The paper presents this as an example rather than as a universal benchmark. It therefore demonstrates internal consistency of the implementation under favorable conditions, not guaranteed robustness under all empirical deviations from the model.

A plausible implication is that the example serves more as calibration of the computational pipeline than as a comprehensive validation study. The main value of the reported performance lies in showing that the AD-compatible likelihood, numerical integration machinery, and inference interfaces work coherently in a realistic package workflow.

6. Relation to adjacent methods, assumptions, and limitations

The package’s relationship to Ringbauer, Coop, and Barton (2017) is direct and central. What is implemented from that work is the inference scheme based on recent coalescence in continuous space and the expected sharing of long IBD blocks as a function of pairwise distance, block length, dispersal, and effective density. The package reproduces the core equations and supports the original analytically tractable density models. Its main extensions are a general-purpose implementation for arbitrary $G$5 via numerical integration, automatic-differentiation-compatible likelihood evaluation, integration with Julia’s optimization and Bayesian inference ecosystem, and practical preprocessing and simulation workflows (Jiménez et al., 9 Jul 2025).

Several caveats are explicit. First, inference depends on the quality of IBD block detection, and IBD calling errors are common. False positives, false negatives, and length misestimation can bias inference. Second, because the method uses composite likelihood, posterior uncertainty and confidence intervals may be too optimistic. The paper explicitly notes that composite-likelihood-based inference tends to be overconfident, underestimating posterior uncertainty and producing confidence intervals that are too narrow. Third, identifiability can be challenging: dispersal and density affect IBD-sharing patterns jointly, and reliable estimation requires enough samples, a broad enough range of pairwise distances, and sufficient numbers of detected IBD blocks across informative length ranges. Fourth, the continuous-space diffusion approximation may fit some species or timescales better than others, especially if barriers, anisotropy, habitat heterogeneity, or leptokurtic dispersal are important. Fifth, effective density is not census density; it is the coalescent-scale parameter entering the local coalescence rate (Jiménez et al., 9 Jul 2025).

These limitations connect IdentityByDescentDispersal.jl to several adjacent literatures. Heterogeneous-space extensions of long-haplotype inference replace homogeneous diffusion by skew diffusion and piecewise neighborhood size, showing how sharp interfaces can be handled within a related composite-likelihood framework (Forien et al., 2017). Long-range dispersal theory based on generalized spatial $G$6-Fleming-Viot models further suggests that ancestral motion and coalescence structure can decouple under power-law dispersal, so Brownian local-coalescence assumptions are only one corner of a broader model space (Forien et al., 2022). This suggests that the package is best interpreted as a high-quality implementation of a specific continuous-space diffusion framework rather than as a universal engine for all forms of spatial ancestry.

Even within nonspatial tract theory, recent work has stressed that mutation, gene conversion, finite marker density, and selection can alter the observable tract spectrum and even prevent a single constant $G$7 from fitting all tract lengths under selection (Santiago, 5 May 2026). That does not invalidate IdentityByDescentDispersal.jl, but it clarifies that tract-based spatial inference remains sensitive to the observational and evolutionary regime.

In summary, IdentityByDescentDispersal.jl makes a previously theory-heavy inference strategy operational. It provides a user-facing implementation for estimating recent effective dispersal and effective density from spatial genomic data by exploiting the fact that long IBD blocks are footprints of recent coalescence, and that their abundance declines with both time since common ancestry and geographic distance in a way predicted by spatial coalescent theory (Jiménez et al., 9 Jul 2025).