ibdsegments (version 1.0.1)

convolve_total_ibd_dists: Convolve IBD distributions to obtain the distribution of the sum

Description

Chromosome-wise IBD distributions obtained from the total_ibd_dist function can be convoluted manually using the convolve_total_ibd_dists function. This allows finer control of the procedure by controlling the number of gridpoints used in the FFT and the threshold for point masses to be retained.

Usage

convolve_total_ibd_dists(
  ...,
  point_mass_eps = 1e-09,
  number_of_gridpoints_exponent = 12
)

Value

Object of class total_ibd_dist

Arguments

...

ibd dists.

point_mass_eps

Point masses smaller than this value are discarded.

number_of_gridpoints_exponent

Default is 12.

Details

The convolve_total_ibd_dists implements a convolution procedure based on a self contained variant of the recipe implemented in the distr package adapted to this use case. In particular, the IBD distribution for one chromosome is often a mixture of two point masses and continuous with finite support otherwise. Convolution increases the number of point masses and decreases their probability mass. This function assumes that small point masses are not of specific interest and will discard the point masses when the probability mass is smaller than point_mass_eps with a default value of 1e-9. For typical pedigree relationships this means that the IBD distribution of more than a few chromosomes is treated as a continuous distribution admitting a density function.

The number_of_gridpoints_exponent controls the density of gridpoints in the FFT. By default this is 12 which means that 2^12=4096 gridpoints are used. Increasing this parameter improves accuracy at the cost of increased runtime and memory use.

The point masses are of particular interest in some applications. For example, the probability that no part of the autosomal genome is inherited may be of interest. In that case, the point masses should not be discarded and the d_cibd function may be used. See the example below, for further details.

Examples

## Convolution of IBD distributions for half siblings at chromosome 1 and 2

# define half sib pedigree
ped_hs <- pedtools::halfSibPed()

# obtain chromosome-wise distributions
d1 <- total_ibd_dist(pedigree = ped_hs, chromosome_length = 267.77)
d2 <- total_ibd_dist(pedigree = ped_hs, chromosome_length = 251.73)

convolve_total_ibd_dists(d1, d2) # 4 point masses

## Accuracy of convolution depends on number of gridpoints

L <- c(267.77, 251.73, 218.31, 202.89, 197.08, 186.02, 178.4, 161.54,
       157.35, 169.28, 154.5, 165.49, 127.23, 116, 117.32, 126.59, 129.53,
       116.52, 106.35, 107.76, 62.88, 70.84)

# obtain chromosome-wise distributions for half siblings
hs <- total_ibd_dist(pedigree = ped_hs,
                     chromosome_length = L, convolve = FALSE)

# obtain moments of the sum by summing the moments..
mean_hat <- sum(sapply(hs, E))
sd_hat <- sqrt(sum(sapply(hs, var)))

# .. or by summing the distributions with varying numbers of gridpoints
k <- 6:10
sd_hat_by_k <- sapply(k, function(k) sd(convolve_total_ibd_dists(hs,
                                        number_of_gridpoints_exponent = k)))
mean_hat_by_k <- sapply(k, function(k) E(convolve_total_ibd_dists(hs,
                                        number_of_gridpoints_exponent = k)))

plot(k, mean_hat_by_k)
abline(h = mean_hat, lty = 2)

plot(k, sd_hat_by_k)
abline(h = sd_hat, lty = 2)