Package {ibdfindr}

Title:	HMM Toolkit for Inferring IBD Segments from SNP Genotypes
Version:	0.4.0
Description:	Implements continuous-time hidden Markov models (HMMs) to infer identity-by-descent (IBD) segments shared by two individuals from their single-nucleotide polymorphism (SNP) genotypes. Provides posterior probabilities at each marker (forward-backward algorithm), prediction of IBD segments (Viterbi algorithm), and functions for visualising results. Supports both autosomal data and X-chromosomal data. The current model has two states, non-IBD and IBD1, and is intended for unilineal relationships. The methodology and package are described in Vigeland et al. (2026) <doi:10.1016/j.fsigen.2025.103409>.
License:	GPL (≥ 3)
URL:	https://github.com/magnusdv/ibdfindr
BugReports:	https://github.com/magnusdv/ibdfindr/issues
Depends:	R (≥ 4.4)
Imports:	forrel, ggplot2, ibdsim2, pedtools, ribd
Suggests:	testthat (≥ 3.0.0)
Config/roxygen2/version:	8.1.0
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-GB
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-08-31 20:23:20 UTC; magnu
Author:	Magnus Dehli Vigeland [aut, cre]
Maintainer:	Magnus Dehli Vigeland <m.d.vigeland@medisin.uio.no>
Repository:	CRAN
Date/Publication:	2026-08-31 22:50:02 UTC

ibdfindr: HMM Toolkit for Inferring IBD Segments from SNP Genotypes

Description

Implements continuous-time hidden Markov models (HMMs) to infer identity-by-descent (IBD) segments shared by two individuals from their single-nucleotide polymorphism (SNP) genotypes. Provides posterior probabilities at each marker (forward-backward algorithm), prediction of IBD segments (Viterbi algorithm), and functions for visualising results. Supports both autosomal data and X-chromosomal data. The current model has two states, non-IBD and IBD1, and is intended for unilineal relationships.

Author(s)

Maintainer: Magnus Dehli Vigeland m.d.vigeland@medisin.uio.no (ORCID)

Authors:

• Magnus Dehli Vigeland m.d.vigeland@medisin.uio.no (ORCID)

See Also

Useful links:

• https://github.com/magnusdv/ibdfindr

• Report bugs at https://github.com/magnusdv/ibdfindr/issues

Dataset with X-chromosomal SNP genotypes for two brothers

Description

Simulated genotypes for two brothers at the X-chromosomal SNPs included in the FORCE panel (Tillmar et al., 2021). The data was generated with the ibdsim2 package.

Usage

brothersX

Format

A tibble with 246 rows and 9 variables:

• CHROM: Chromosome label

• MARKER: SNP identifier

• MB: Physical position in megabases

• CM: Map position in centimorgans

• A1: First SNP allele

• A2: Second SNP allele

• FREQ1: Population frequency of A1

• ID1: Genotype of individual 1

• ID2: Genotype of individual 2

References

Tillmar et al. The FORCE Panel: An All-in-One SNP Marker Set for Confirming Investigative Genetic Genealogy Leads and for General Forensic Applications. Genes. (2021)

Examples

brothersX

Precision and Recall for IBD segment calls

Description

Computes the precision and recall of IBD segment calls (typically from findIBD()) against a truth set of IBD segments.

Usage

computePR(call, truth, details = FALSE)

Arguments

Value

A data frame with columns Precision and Recall. If details = TRUE, additional columns F1, CallTotal (total length of called segments) and TruthTotal (total length of truth segments) are included.

Examples

# Built-in X example
ibd = findIBD(brothersX)

# True segments (see code in `data-raw/brothersX.R`)
truth = data.frame(chrom = 23,
                   startCM = c(0, 66.841, 138.834),
                   endCM = c(10.867, 120.835, 164.398))

computePR(ibd$segments, truth)
plotIBD(ibd, refSegs = truth)

Dataset with autosomal SNP genotypes for two cousins

Description

Simulated genotypes for two individuals at the autosomal kinship SNPs from the FORCE panel (Tillmar et al., 2021). The data was generated with the ibdsim2 package, assuming a relationship of first cousins.

Usage

cousinsDemo

Format

A tibble with 3,915 rows and 9 variables:

• CHROM: Chromosome label

• MARKER: SNP identifier

• MB: Physical position in megabases

• CM: Map position in centimorgans

• A1: First SNP allele

• A2: Second SNP allele

• FREQ1: Population frequency of A1

• ID1: Genotype of individual 1

• ID2: Genotype of individual 2

References

Tillmar et al. The FORCE Panel: An All-in-One SNP Marker Set for Confirming Investigative Genetic Genealogy Leads and for General Forensic Applications. Genes. (2021)

Examples

cousinsDemo

All-in-one workflow for finding IBD segments

Description

This function conveniently wraps the key steps of the package. It first fits a continuous-time HMM to the data (fitHMM()), then identifies IBD segments (findSegments()), and finally computes the marker-wise posterior IBD probability at each marker locus (ibdPosteriors()). The result can be passed straight to plotIBD() for visualisation.

Usage

findIBD(
  data,
  ids = NULL,
  k1 = NULL,
  a = NULL,
  err = 0,
  method = NULL,
  thompson = FALSE,
  verbose = TRUE
)

Arguments

Details

The HMM has two states, non-IBD and IBD1, and does not model IBD2. See fitHMM() for details.

Value

A list with the following elements:

• ids: The two analysed individuals

• k1: HMM parameter (estimated or provided)

• a: HMM parameter (estimated or provided)

• segments: Data frame with IBD segments

• posteriors: Data frame with posterior IBD probabilities at each marker

See Also

fitHMM(), findSegments(), ibdPosteriors(), plotIBD()

Examples

ibd = findIBD(brothersX)
plotIBD(ibd)

Identify IBD segments

Description

Identifies genomic segments shared identical-by-descent (IBD) between two individuals from SNP marker data. The method applies a hidden Markov model (HMM) along each chromosome, with states 0 (non-IBD) and 1 (IBD), and uses the Viterbi algorithm to infer the most likely sequence of states.

Usage

findSegments(
  data,
  ids = NULL,
  k1,
  a,
  err = 0,
  prepped = FALSE,
  verbose = FALSE
)

Arguments

Value

Data frame with columns chrom, startCM, endCM and n (number of markers). startCM and endCM are the positions of the first and last markers assigned to each segment. If no segments are found, the data frame has zero rows.

See Also

plotIBD()

Examples

findSegments(cousinsDemo, k1 = 0.2, a = 5)

Fit a Hidden Markov Model to genotype data

Description

This function fits a continuous-time HMM to the provided genotype data. The parameter k1 is the stationary probability of IBD1, while a is the transition rate per Morgan.

Usage

fitHMM(
  data,
  ids = NULL,
  k1 = NULL,
  a = NULL,
  err = 0,
  method = "L-BFGS-B",
  thompson = FALSE,
  prepped = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

In the current implementation, the model has two states, non-IBD and IBD1, and is intended for unilineal relationships. It may give misleading results for full siblings or other relationships involving IBD2 sharing.

Markers with equal cM positions are treated as completely linked, with no state transition between them. Uninformative or unusable markers are reported and removed before analysis. This includes monomorphic markers (freq1 equal to 0 or 1), markers with missing annotation, markers with missing genotypes, and markers with impossible genotype/frequency combinations.

By default both parameters are optimised jointly using stats::optim().

If thompson = TRUE, k1 is first estimated by forrel::ibdEstimate(), using the approach of Thompson (1975). This step uses marker-wise likelihoods and does not model linkage between markers. The parameter a is subsequently estimated conditional on k1.

Value

A list containing the fitted parameters k1 and a.

References

Thompson, E. A. (1975). The estimation of pairwise relationships. Annals of Human Genetics 39.

See Also

totalLoglik(), forrel::ibdEstimate()

Examples

fitHMM(cousinsDemo)

IBD posteriors

Description

Computes the posterior probability of identity‐by‐descent (IBD) at each marker locus via the HMM forward–backward algorithm.

Usage

ibdPosteriors(
  data,
  ids = NULL,
  k1,
  a,
  err = 0,
  prepped = FALSE,
  verbose = FALSE
)

Arguments

Value

A data frame with the processed marker data and a column post containing the posterior IBD probability at each marker.

See Also

plotIBD()

Examples

ibdPosteriors(cousinsDemo, k1 = 0.2, a = 5)

Plot IBD segments and posteriors

Description

Plot IBD segments and posteriors

Usage

plotIBD(
  x,
  segments = NULL,
  chrom = NULL,
  ncol = NULL,
  title = NA,
  base_size = 12,
  refSegs = NULL
)

Arguments

Value

A ggplot2 plot.

See Also

findIBD(), findSegments(), ibdPosteriors()

Examples

x = subset(cousinsDemo, CHROM %in% 3:4)
ibd = findIBD(x, k1 = 0.2, a = 5)
plotIBD(ibd)

Identify problematic markers

Description

Identifies markers with invalid or impossible HMM emission probabilities. Note that monomorphic markers (freq1 equal to 0 or 1) are not included.

Usage

problemMarkers(data, ids = NULL, err = 0, prepped = FALSE)

Arguments

Value

A data frame containing the problematic markers, or NULL if none are found. If prepped = TRUE, an integer vector of row indices is returned instead.

Total log-likelihood for observed data

Description

This function computes the total log-likelihood of the observed data, under the hidden Markov model. It is mainly for internal use, especially fitHMM().

Usage

totalLoglik(data, ids = NULL, k1, a, err = 0, prepped = FALSE)

Arguments

Value

A number: The total log-likelihood of the data under the HMM model.

Examples

totalLoglik(cousinsDemo, k1 = 0.2, a = 5)