sandwrm: An R Package for Estimating Wright's Neighbourhood Size and Species‐Level Genetic Diversity

ABSTRACT

In most natural populations, individuals in close proximity are more related on average than those at greater distances; this pattern gives rise to geographic population genetic structure. Despite extensive theoretical work on spatial population genetics, few empirical methods exist to estimate the components of theoretical models of genetic relatedness in continuous space. One classic model of relatedness in continuous space is the Wright‐Malécot model, which predicts that the probability of identity‐by‐descent decays as a function of geographic distances. The shape of this decay curve is dictated by the dynamics of local dispersal and mating, as well as population density. This model can be reformulated to describe the probability of identity‐by‐state, in which case the curve decays to an asymptote, the value of which is determined by the historical demography of the population. Collectively, these features can be modelled in a likelihood‐based framework to estimate neighbourhood size—a localized measure of the rate of genetic drift—and long‐term diversity from pairwise genetic and geographic distance. In this article, we introduce the R package sandwrm (Spatial Analysis of Neighbourhood size and Diversity using WRight‐Malécot), which takes a Bayesian approach to estimate key parameters of populations that are both dispersal‐limited (i.e., do not traverse the entire range in a single generation) and distributed continuously across a landscape. The R package can be installed from the GitHub repository, https://github.com/zachbhancock/sandwrm.

1. Introduction

Many organisms in nature are dispersal‐limited and tend to be more related to individuals nearby than to those far away. This pattern, known as isolation‐by‐distance (IBD) (Wright 1943), has been widely documented in a diversity of organisms (e.g., Aguillon et al. 2017; Ramachandran et al. 2005; Rousset 1997; Sharbel et al. 2000), and reflects the reality that most organisms move, forage, compete, and locate mates in continuous geographic space (Battey et al. 2020; Bradburd and Ralph 2019). However, most population genetic inference programs that have been used in empirical studies treat organisms as well‐mixed, discrete populations connected by occasional migration (e.g., Alexander et al. 2009; Beerli et al. 2019; Epperson 2003; Pritchard et al. 2000). Past work has shown that many population genetic summary statistics, like Watterson's $\theta$ and Tajima's $D$, as well as estimates of population genetic structure, are biased in the presence of continuous structure (Battey et al. 2020; Bradburd et al. 2018; Frantz et al. 2009). In addition, continuous population structure can lead genome‐wide association studies (GWAS) to identify spurious genetic associations with completely environmentally‐determined traits (Battey et al. 2020).

While most popular inference programs utilize models that are non‐spatial, theoretical population genetics has a long history of describing populations in continuous space. The first of these models was introduced by Sewall Wright (1943, 1946) and Gustave Malécot (1948); they imagined a homogeneous, infinite landscape in which individuals disperse in two dimensions following a bivariate Gaussian distribution with a mean of zero and standard deviation in each dimension of $\sigma$, which is interpreted as the ‘dispersal distance.’ Elaborating on the Wright‐Malécot model, Barton et al. (2002) formalized the probability that individuals are identical‐by‐descent, $F_{i,j}$, given $\sigma$ and the geographic distance, $d_{i,j}$, separating individuals $i$ and $j$ as:

$$F_{i,j}=\left(\frac{1}{4\mathit{\pi \rho }{\sigma }^2}\right)K_0\left(\sqrt{2\mu }\frac{d_{i,j}}{{\sigma }^2}\right)$$ (1)

where $\rho$ is the population density, $\pi$ is the mathematical constant, $\mu$ is the mutation rate, and $K_0$ is a modified Bessel function of the second kind (Barton et al. 2002; Malécot 1948; Ringbauer et al. 2017; Wright 1943). (We note here that both isolation by distance and identity by descent are frequently abbreviated as ‘IBD.’ We have attempted to avoid ambiguity by referring only to isolation by distance as IBD, and referring to identity by descent using the complete phrase or the quantity $F_{i,j}$ to denote the probability of identity by descent between individuals $i$ and $j$.) A key value in this expression is the compound parameter $4\mathit{\pi \rho }{\sigma }^2$, which is known as ‘Wright's neighbourhood size’ ($\mathit{N}$). This parameter captures the number of potential breeding individuals within a radius defined by the per‐generation parent‐offspring dispersal distance, $\sigma$. Thus, $\mathit{N}$ captures the local rate of genetic drift. Using simulations, Hancock et al. (2024) demonstrated that estimates of $\mathit{N}$ are relatively insensitive to demographic shifts that occurred long ago, and tend to reflect contemporary population dynamics. Furthermore, for two‐dimensional systems, it determines the slope of the isolation‐by‐distance curve, and thus informs us about the scale of spatial autocorrelation of genetic ancestry.

While $\mathit{N}$ captures local demographic and evolutionary dynamics that might have occurred in the recent past, researchers are often also interested in long‐term, global trends across an entire metapopulation, or even a species' range. These trends can inform us about ancient population bottlenecks or expansions, inbreeding, and a species' adaptive potential (Charlesworth 2009; Mable 2019; Willi et al. 2006). While the slope of the isolation‐by‐distance curve in two‐dimensional habitats is shaped by $\mathit{N}$, the long‐term inbreeding effective population size ($N_e$) is reflected by the asymptote of pairwise sequence dissimilarity against geographic distance. An estimator of this long‐term value was introduced by Hancock et al. (2024) and dubbed ‘collecting‐phase $\pi$’ (${\pi }_c$), so named because it captures the outcome of demographic processes from the collecting phase of the coalescent (Wilkins 2004). This parameter can be thought of as the diversity of a spatially over‐dispersed sample of individuals (i.e., not biased by spatial autocorrelation of ancestry). See Hancock et al. (2024) for additional details.

Historically, $\mathit{N}$ has been estimated almost exclusively by regressing linearized $F_{\mathrm{ST}}$ (i.e., $F_{\mathrm{ST}}$/(1 − F _ST)) against geographic distance, a method introduced by Rousset (1997). Recently, Hancock et al. (2024) introduced a Bayesian statistical approach for jointly estimating neighbourhood size ($\mathit{N}$) and long‐term diversity (${\pi }_c$) from pairwise genetic and geographic distance data. Hancock et al. (2024), using simulations and an empirical dataset of the two‐form bumblebee ( Bombus bifarius ), compared the two methods and found that Rousset's method was downwardly biased, sometimes giving negative values for $\mathit{N}$, and had extremely large variances, especially at higher population densities. Furthermore, Rousset's method requires a user to make arbitrary decisions about how to group individuals within populations to calculate pairwise $F_{\mathrm{ST}}$. Alternatively, our Bayesian implementation of the Wright‐Malécot model resulted in greater accuracy, much lower variances, and, because it utilizes pairwise genetic distances at the individual‐level, avoids the pitfalls of aggregating individuals.

In this paper, we present sandwrm (Spatial Analysis of Neighbourhood size and Diversity using WRight‐Malécot), a user‐friendly R‐package for the analysis of spatial genetic data. Specifically, sandwrm employs the model from Hancock et al. (2024) to estimate Wright's neighbourhood size and $\pi$ in the collecting phase, and generates diagnostic plots for ease of visualizing parameter estimates and evaluating model fit.

2. Materials and Methods

2.1. Usage

The sandwrm package can be installed from the GitHub repository https://github.com/zachbhancock/sandwrm, where users will also find installation instructions and a basic tutorial. Below, we briefly describe how sandwrm can be used, including a discussion of data preparation, analysis choices, and explanation of model output and interpretation.

The sandwrm package is coded in the R programming language (R Core Team 2022) wrapped around an inference engine implemented in rstan (Stan Development Team 2025). Details of the model are described in Hancock et al. (2024), but will be expounded upon briefly here.

2.2. Model

We model the pairwise sample homozygosity ($\widehat{\mathrm{\Omega }}$), which we define as the complement of pairwise diversity, i.e., 1 − D _XY, as a draw from a Wishart distribution:

$$\widehat{\mathrm{\Omega }}\sim \mathcal{W}\left(\mathrm{\Omega },L\right)$$ (2)

where $L$ is the degrees of freedom of the Wishart (which we discuss further below), and $\mathrm{\Omega }$ is a parametric covariance that is a function of geographic distance and the parameters of our model. Specifically,

$${\mathrm{\Omega }}_{i,j}=F_{i,j}+\left(1-F_{i,j}\right)s+{\delta }_{i,j}{\eta }_i$$ (3)

where $s=1-{\pi }_c$ (i.e., 1 minus $\pi$ in the collecting phase), ${\delta }_{i,j}$ is the Kronecker $\delta$, and ${\eta }_i$ describes inbreeding specific to the ith individual (Hancock et al. 2024; Ringbauer et al. 2017). The quantity $F_{i,j}$ is the probability of identity by descent between samples $i$ and $j$, and is defined as a function of the geographic distance, $d_{i,j}$, between them:

$$F_{i,j}=\left\{\begin{array}{ll}\gamma ,& \text{if}{d}_{i,j}\le \kappa \\ \frac{K_0\left(\sqrt{m}{d}_{i,j}\right)}{\mathit{N}},& \text{if}{d}_{i,j}>\kappa \end{array}\right.$$ (4)

where $m$ is a compound parameter equal to $2\mu /{\sigma }^2$, $\gamma$ is the rate of coalescence between nearby individuals, and ‘nearby’ (i.e., within distance $\kappa$ of each other) is defined as near enough that they can be considered to be randomly mating (see Hancock et al. (2024) for an additional discussion).

2.3. Data Preparation

To execute the model, users specify a pairwise genetic distance matrix. The genetic distance calculated should be pairwise $\pi$, also known as $D_{\mathit{XY}}$ – the average pairwise sequence dissimilarity per base pair. Note that the appropriate denominator in calculating $\pi$ is the total number of basepairs genotyped in both samples being compared. Pairwise $\pi$ calculated solely from polymorphic sites should not be used in this analysis. An avenue for researchers to acquire a pairwise $\pi$ matrix is to generate it using pixy (Korunes and Samuk 2021), which accepts a VCF file that includes polymorphic and monomorphic sites. Researchers who assembled restriction‐associated DNA (RAD) tags or other short‐read datasets can generate a VCF file with included monomorphic sites using STACKS (Rochette et al. 2019) with the call ‐‐vcf‐all in the populations function. From this, pixy will estimate pairwise $\pi$, which can be converted to a matrix for the sandwrm analysis. Additional documentation on how to prepare a VCF file that contains monomorphic and polymorphic sites can be found in the pixy documentation. For researchers with low‐coverage, whole genome data, pairwise genetic distance matrices can be acquired from methods such as distANGSD (Zhao et al. 2022).

Users must also specify a pairwise geographic distance matrix. Pairwise geographic distance can be in whatever units the user wishes (though note that estimated neighbourhood size is in units of individuals per area, so the units chosen will affect the estimated value of $\mathit{N}$). For sampling over large geographic regions, users may wish to calculate great‐circle distance; for sampling on smaller spatial scales, users may wish to use distances based on, for example, Universal Transverse Mercator (UTM) coordinates, which are more accurate over smaller scales.

In addition to pairwise genetic and geographic distances, there are two other quantities that users must specify in order to initiate a sandwrm analysis: the number of independent loci in their dataset ($L$) and the spatial cutoff within which the model of isolation by distance no longer applies ($\kappa$).

The parameter $L$ determines the degrees of freedom of the Wishart distribution used to model the data; larger values indicate higher confidence and concomitantly lower acceptable ‘noise’ in inference. In principle, $L$ is the number of independent (i.e., unlinked) loci used to estimate pairwise genetic relatedness. In practice, it is often unclear precisely what value to specify for $L$ because loci may be in linkage disequilibrium (LD) over long stretches of the genome. Thinning SNPs for LD (e.g., by retaining only a single SNP per RAD locus) may not completely remove SNPs that are evolving nonindependently, which can result in an inflated confidence due to pseudoreplication. In addition, $L$ only captures the uncertainty associated with estimates of pairwise homozygosity; it does not capture uncertainty in the Wright‐Malécot model itself (i.e., uncertainty due to stochasticity in the genealogical and geographic processes that generate the observed distribution of individuals and their relatedness). As a result, very large values of $L$ made possible by, for example, whole‐genome resequencing datasets, could lead to unrealistically low uncertainty. We recommend that researchers test a range of values of $L$ below the number of base pairs obtained after thinning for LD.

The units of $\kappa$ are the same as the distance matrix (e.g., if the geographic distance is measured in kilometres, the dispersal distance is in units of kilometres). Importantly, if the random‐mating distance is unknown, this value can be set arbitrarily low without significantly affecting the model performance, but if it is set too high it might deplete the signal of isolation‐by‐distance, especially if the signal of correlation between ancestry and geographic distance decays over very short distances.

To begin a sandwrm analysis, users specify these quantities (genetic distance, geographic distance, $L$, and $\kappa$) as arguments to the prepareData function, which will generate an R object that can then be passed to the function sandwrm.

The function sandwrm initiates a Markov chain Monte Carlo (MCMC) analysis that characterizes the posterior distribution of all model parameters, including $\mathit{N}$ and ${\pi }_c$. Users will need to specify how many independent MCMC chains they would like to run and how many steps for these chains to take. We recommend at least two independent chains to confirm that both are converging on the same posterior distribution. The Hamiltonian Monte Carlo algorithm implemented in rstan is very efficient, so most runs of this model are able to mix effectively in 5000 iterations or fewer (minimum recommended number of iterations is 2000). The first 50% of iterations are discarded as burn‐in, as recommended by the Stan development team (Stan Development Team 2025). A typical run would look something like:

    sandwrm(dataBlock=dataBlock,             nChains=4,             nIter=2000,             prefix="test" 

By default, a successful call to sandwrm analysis generates two output files: an R object saved in binary file format, and a PDF that includes various figures, both of which will have a file name determined by the ‘prefix’ argument specified. The first of these figures displays trace plots of the MCMC to visually inspect for convergence (Figure 1). The second is a series of panels showing the joint marginal distributions of all pairs of estimated parameters (Figure 2). The last plot shows the fit of the model to the empirical data (Figure 3).

FIGURE 1.

MCMC trace plots produced by sandwrm for the posterior probability and each estimated parameter. Different colours represent the four independent MCMC chains.

FIGURE 2.

Example output of the correlations panels between estimated parameters in sandwrm. The function will produce figures for each independent MCMC chain with the colours matching those from Figure 1.

FIGURE 3.

Model fit output from a single chain of a sandwrm run, shown using an IBD plot. Dark circles are the empirical estimates of pairwise $\pi$, blue circles are the fit of the model. The dashed line is $\kappa$.

The output R object file includes all the estimated parameters from each independent MCMC chain. Each of the parameters and their abbreviations are listed in Table 1.

TABLE 1.

Table defining each parameter of the Wright‐Malécot model.

Parameter	Name in sandwrm	Description
$\mathit{N}$	nbhd	Wright's neighbourhood size
${\pi }_c$	1 − s	Species‐level diversity
$m$	m	Scaled mutation rate
$\gamma$	inDeme	Local coalescent rate
$\eta$	nugget	Spatial nugget

To establish benchmarks for model runtime, we recorded the computational run‐time for a single MCMC chain for datasets consisting of 25, 50, or 100 individuals ($N$) and of 1000, 10,000, or 100,000 independent loci ($L$). The test dataset used for benchmarking is the same as that used in the ‘Example workflow’ section below. To calculate runtime, we used the package tictoc (Izrailev 2025).

3. Results

3.1. Benchmarking

Across the tested datasets, $L$ had a minimal impact on run‐time, whereas increasing sample size led to an approximately cubic increase in run‐time (Figure 4). This faster‐than‐linear increase in run‐time with sample size is unavoidable, as the likelihood calculation for the Wishart distribution involves inverting a covariance matrix, an operation that has a time complexity of $O\left(n^3\right)$.

FIGURE 4.

Histogram of Wright's neighbourhood size ($\mathit{N}$) estimated from the sandwrm example dataset across all four chains produced by the function nbhdHistogram.

3.2. Example Workflow

In this section, we provide an example workflow. The dataset for this example is included within the sandwrm package as.

example_locs.txt example_pwp.txt

This is a simulated dataset of a continuous‐space model in the forward‐time simulator SLiM v.3.6 (Haller and Messer 2019) as described in Hancock et al. (2024). The locations file contains coordinates for each individual and can be converted into a distance matrix as follows:

  library(fields)  data("example_locs", "example_pwp")  coords <- example_locs[,c("x","y")]  geoDist <- rdist(coords)  genDist <- as.matrix(example_pwp) #convert into a matrix

Next, the function prepareData can be used to construct the data block, which is a list of several components that is required to run sandwrm. The function is used as follows:

  L <- 1e4 #number of independent loci  k <- 0.25 #kappa parameter  dataBlock <- prepareData(genDist = genDist, geoDist = geoDist, L = L, k = k)

With the data block constructed, the sandwrm is called as indicated above. Two functions for quickly visualizing the results are included in sandwrm: nbhdHistogram and piHistogram, which generate histograms of estimated $\mathit{N}$ and species diversity (${\pi }_c$), respectively, across all chains (Figure 5).

FIGURE 5.

Benchmarking results for matrix sizes of 25, 50, and 100 across three different values of $L$: 1000, 10,000, and 100,000.

To extract parameter estimates directly from the out.Robj file, users can utilise the plyr and dplyr packages as follows:

    load("out.Robj")    nbhd <- rstan::extract(out$fit, "nbhd",     inc_warmup=TRUE, permute=FALSE)    #make long    nbhd_long <- plyr::adply(nbhd, c(1, 2, 3)) %>%     dplyr::rename("iteration"="iterations",     "chain"="chains",     "nbhd"="V1") %>%    mutate(chain = gsub("chain:", "", chain)) %>%     dplyr::select(-parameters)    head(nbhd_long)      iteration chain     nbhd1         1     1 14.400592         2     1 14.590383         3     1 14.635644         4     1 14.826585         5     1 14.932706         6     1 14.54744

The remaining parameters can also be extracted in this way; see Table 1 for all estimated parameters in the Robj file.

4. Discussion

Despite the ubiquity of organisms in nature that are both dispersal‐limited and continuously distributed across the landscape, relatively few methods exist for using DNA sequence data to learn about important theoretical parameters like Wright's neighbourhood size. For methods that do exist, even fewer have been packaged in such a way as to permit general use among empiricists. In this article, we describe a new R package, sandwrm, intended to remedy this issue by providing users with an easy, straightforward tool for estimating both $\mathit{N}$ and a novel statistic that captures genetic diversity at the species‐level and is unbiased by local structure, ${\pi }_c$. We have provided a general workflow for how to use the package; additional tutorials can be found at https://github.com/zachbhancock/sandwrm.

There are several biological questions that sandwrm could aid in investigating. For example, sandwrm enables researchers to compare variation in $\mathit{N}$ across populations or species. Because $\mathit{N}$ represents the rate of genetic drift locally, it can be used to identify regions of a species' range that are less dense, have reduced adaptive capacity, and potentially suffering from a heightened genetic load. Between species, estimates of $\mathit{N}$ could be regressed against life‐history traits such as body size, range size, developmental mode, etc. to search for potential drivers of differences in neighbourhood size. Combined with estimates of effective dispersal (from, e.g., Smith and Kern 2023; Smith et al. 2023), estimates of neighbourhood size can yield information on effective density. Conversely, if researchers have reasonable estimates of effective density, that can be combined with estimates of $\mathit{N}$ to generate estimates of effective dispersal. Additionally, ${\pi }_c$ could serve as a proxy for long‐term $N_e$ in broad‐scale comparisons across species as it is unbiased by spatial sampling, unlike many other estimators of $N_e$. For example, Toczydlowski et al. (2025) identified correlations between ${\pi }_c$, life‐history traits, and range features of marine organisms to determine factors that shape marine genetic diversity.

There are several limitations to sandwrm, as were discussed in Hancock et al. (2024). An important assumption is that dispersal is random and approximately Gaussian‐distributed with a mean of zero. Violations of this assumption, as in the case of directional gene flow caused by wind or river currents, could lead to biased estimates of $\mathit{N}$. Similarly, the model assumes that the habitat is homogeneous such that there are no major barriers to gene flow across the sample locations. Lastly, the model relies on user‐specified values that can be difficult to know empirically, such as $L$ and $\kappa$; however, users can easily try different input values to assess their impact on parameter inference.

Author Contributions

Z.B.H. created the R package and performed the benchmarking, and G.S.B. devised the model.

Funding

Research reported in this publication was supported by the National Institute of General Medical Sciences of the National Institutes of Health under Award Number R35GM137919 (awarded to GSB). The content is solely the responsibility of the authors and does not necessarily represent the official views of the NIH.

Ethics Statement

The authors have nothing to report.

Conflicts of Interest

The authors declare no conflicts of interest.

Data Availability Statement

The package sandwrm can be installed in its most up‐to‐date form from the GitHub repository: https://github.com/zachbhancock/sandwrm.