Package 'dvir'

Description

AM-driven identification, i.e., considering one AM family at a time. Simple families (exactly 1 missing) are handled directly from the LR matrix, while nonsimple families are analysed with dviJoint().

Usage

amDrivenDVI(
  dvi,
  fams = NULL,
  threshold = 10000,
  threshold2 = max(1, threshold/10),
  verbose = TRUE
)

Arguments

Details

Note: This function assumes that undisputed identifications have been removed. Strange outputs may occur otherwise.

Value

A list of dviReduced and summary.

Examples

w = amDrivenDVI(example2)
w$summary
w$dviReduced

# Bigger example: Undisputed first
u = findUndisputed(planecrash)
u$summary

# AM-driven analysis of the remaining
amDrivenDVI(u$dviReduced, threshold2 = 500)

Description

Compute posterior pairing and non-pairing probabilities, based on a prior and the output from jointDVI().

Usage

Bmarginal(jointRes, missing, prior = NULL)

Arguments

Details

The prior assigns a probability to each assignment, each row of jointRes. If the prior is not specified, a flat prior is used. The prior needs not sum to 1 since the user may rather choose a flat prior on the a priori possible assignments.

Value

A matrix. Row i gives the posterior probability that victim i is one of the missing persons or someone else, denoted '*'.

See Also

jointDVI()

Examples

jointRes = jointDVI(example1)

Bmarginal(jointRes, example1$missing)

# Artificial example: all but optimal solution excluded by prior
Bmarginal(jointRes, example1$missing, prior = c(1, rep(0,26)))

Description

Each relationship is relative to one missing person per family. Marker data are returned separately by default. Unspecified relatives are placed on the simplest shared branch.

Usage

buildAM(x, mpFormat = c("M", "family"), attachGeno = FALSE, loci = NULL)

Arguments

Value

A list with am (one pedigree or list of components per family), missing (MP labels), issues (family IDs grouped by issue), and geno (genotypes, one column per marker). If attachGeno = TRUE, the genotype data is attached to the am pedigrees. contains markers. Disconnected references remain singletons; construction errors return all singletons.

Examples

x = data.frame(
  Family = rep(c("F1", "F2", "F3"), 1:3),
  Relationship = c("[Mother]", "[Wife]", "[Daughter]",
                   "[Grandmother]", "[Brother]", "[Niece]"),
  Sample = paste0("S", 1:6),
  M1 = c("1/1", "1/2", "2/2", "1/1", "1/2", "2/2"))
x

y = buildAM(x, attachGeno = TRUE)

plotPedList(y$am, hatched = typedMembers, marker = 1)
y$issues

Description

Computes the likelihood ratio comparing the hypotheses that two samples originate from the same individual or from two unrelated individuals.

Usage

directMatch(
  x,
  y,
  g1 = NULL,
  g2 = NULL,
  dropout = 0,
  dropin = 0,
  typingError = 0,
  .lik1 = NULL,
  .lik2 = NULL,
  .skipChecks = FALSE
)

Arguments

Details

For a single marker, the LR is computed as

$LR = \frac{P(G_1,G_2 \mid H_1)} {P(G_1 \mid H_2)P(G_2 \mid H_2)},$

where G1 and G2 are the observed genotypes of the two samples. H1 states that the samples originate from the same individual, and H2 that they originate from unrelated individuals. The overall LR is obtained by multiplying the marker-wise LRs.

With all error probabilities equal to zero, discordant non-missing genotypes give LR = 0. A missing genotype in either sample contributes LR = 1.

Allelic dropout follows the model of Dørum et al. (2015), with alleles dropping out independently with probability dropout. Drop-in and typing error are incorporated according to the model described by Kling et al. (2014) and implemented in the Direct Match feature of Familias. The three error mechanisms are treated independently, and likelihoods are obtained by summing over all possible true genotypes. See also Egeland, Kling & Mostad (2016), Table 3.5 for a simplified version.

Value

A single number.

References

• Dørum G, Kling D, Baeza-Richer C, García-Magariños M, Sæbø S, Desmyter S, Egeland T (2015). "Models and implementation for relationship problems with dropout". International Journal of Legal Medicine, 129, 411-423. doi:10.1007/s00414-014-1046-5

• Kling D, Tillmar AO, Egeland T (2014). "Familias 3 - Extensions and new functionality". FSI: Genetics, 13, 121-127. doi:10.1016/j.fsigen.2014.07.004

• Egeland T, Kling D, Mostad P (2016). Relationship Inference with Familias and R: Statistical Methods in Forensic Genetics. Academic Press. ISBN:9780128024027.

See Also

mergePM().

Examples

afr = c("1" = 0.7, "2" = 0.3)
pm = singletons(c("V1", "V2")) |>
  addMarker(V1 = "1/1", V2 = "1/2", afreq = afr, name = "M")
directMatch(pm[[1]], pm[[2]])
directMatch(pm[[1]], pm[[2]], dropout = 0.05)
directMatch(pm[[1]], pm[[2]], dropin = 0.01)
directMatch(pm[[1]], pm[[2]], typingError = 0.001)
directMatch(pm[[1]], pm[[2]], dropout = 0.05, dropin = 0.01, typingError = 0.001)

Description

Legacy helper for comparing different computational approaches to DVI.

Usage

dviCompare(
  dvi,
  true,
  refs = NULL,
  methods = 1:6,
  markers = NULL,
  threshold = 1,
  simulate = TRUE,
  db = NULL,
  Nsim = 1,
  returnSims = FALSE,
  seed = NULL,
  numCores = 1,
  verbose = TRUE
)

Arguments

Details

NOTE: This is a legacy function, mainly kept for reproducibility of older analyses. It is not part of the recommended dvir workflow. Use with caution.

The following methods are available through the methods parameter:

1. Sequential, without LR updates.

2. Sequential, with LR updates.

3. Sequential (undisputed) + joint (remaining). Always returns the most likely solution(s).

4. Joint - brute force. Always returns the most likely solution(s).

5. Like 3, but returns the winner(s) only if LR > threshold; otherwise the empty assignment.

6. Like 4, but returns the winner(s) only if LR > threshold; otherwise the empty assignment.

Value

A list of solution frequencies for each method, and a vector of true positive rates for each method.

Examples

db = forrel::NorwegianFrequencies[1:6]

# True solution: V1 = M1, while V2/V3 are the siblings M2/M3
true = c("M1", "M2", "M3")


# Increase Nsim for accurate estimates
dviCompare(fire, true = true, db = db, Nsim = 2, seed = 1)

# Simulations can also be generated first
sims = dviCompare(fire, true = true, db = db, Nsim = 2, seed = 1,
                  returnSims = TRUE)
dviCompare(sims, true = true, simulate = FALSE)

Description

DVI data

Usage

dviData(pm, am, missing, generatePairings = TRUE)

checkDVI(
  dvi,
  pairings = NULL,
  errorIfEmpty = FALSE,
  ignoreSex = FALSE,
  verbose = TRUE
)

Arguments

Value

An object of class dviData, which is basically a list of pm, am, missing and pairings.

Examples

dvi = dviData(pm = singleton("V1"), am = nuclearPed(1), missing = "3")
dvi

checkDVI(dvi)

Description

Based on a dviData object, or output from dviJoint() or jointDVI(), the GLR, the ratio of the maximum likelihood under H0 to the maximum under H1, is calculated for specified hypotheses.

Usage

dviGLR(dvi, pairings = generatePairings(dvi), dviRes = NULL)

Arguments

Details

The Generalised Likelihood Ratio (GLR) statistic is defined as the ratio of the maximum likelihood for the alternatives in the numerator to the maximum in the denominator. The default pairings = dvir::generatePairings(dvi) tests all hypotheses. Specific tests can be specified as shown in an example: pairings = list(V1 = "M1") gives a test for H0: V1 = M1 against H1: V1 != M1. dviRes will be calculated using jointDVI() if not provided.

Value

A data frame with GLRs and SGLR (strict GLR, max replaced by min in the numerator).

Examples

# dviGLR(example2, pairings = list(V1 = "M1"))

# All tests with output from jointDVI
# dviGLR(example2)

Description

Calculates how many rows would be produced by expand.grid.nodup(), either exactly or as a guaranteed lower bound. This is used to detect DVI problems where a joint search would be prohibitive.

Usage

dviGridSize(dvi = NULL, pairings = NULL, ignoreSex = FALSE, max = Inf)

Arguments

Details

Exact counting is done without constructing the full table. The algorithm counts matchings in the bipartite graph between victims and missing persons, treating the non-assignment value "*" as a repeatable choice. For large problems, the function returns a lower bound instead of the exact count. (See Value.)

Value

A list with elements size (a number) and type (either "exact" or "lower bound").

See Also

expand.grid.nodup(), dviJoint(), generatePairings(), ncomb()

Examples

dviGridSize(example1)

pairings = generatePairings(example1)
dviGridSize(pairings = pairings)

Description

dviJoint() performs a joint likelihood search over candidate assignments in a DVI problem, ranking all assignments and returning both PM-oriented and AM-oriented assignment columns. It is used internally by dviSolve() for unresolved complex families. Compared with the legacy jointDVI(), it does not perform preprocessing steps such as exclusions or undisputed matches.

Usage

dviJoint(
  dvi,
  assignments = NULL,
  ignoreSex = FALSE,
  disableMutations = FALSE,
  maxAssign = 1e+05,
  computeLR0 = FALSE,
  numCores = 1,
  cutoff = 0,
  verbose = TRUE,
  progress = interactive()
)

Arguments

Value

A data frame.

Examples

dviJoint(example2)
dviJoint(example2, computeLR0 = TRUE)

Description

Simulates genotypes for the references and missing persons in each AM family, transfers to the PM singletons according to the indicated matching. Remaining victims are simulated as unrelated.

Usage

dviSim(
  dvi,
  N = 1,
  refs = typedMembers(dvi$am),
  truth = NULL,
  seed = NULL,
  conditional = FALSE,
  simplify1 = TRUE,
  verbose = FALSE
)

Arguments

Value

If N = 1, a dviData object similar to the input, but with new genotypes for the pm samples. If N > 1, a list of dviData objects.

See Also

forrel::profileSim().

Examples

# Simulate refs and missing once and plot:
ex = dviSim(example2, N = 1, truth = c(V1 = "M1", V2 = "M2", V3 = "M3"))
plotDVI(ex, marker = 1)

# Two simulations and plot for the first
ex = dviSim(example2, N = 2, truth = c(V1 = "M1", V2 = "M2", V3 = "M3"),
            seed = 1729)
plotDVI(ex[[1]], marker = 1)

Description

Wraps the main dvir workflow for DVI analysis and identification of likely AM–PM matches.

Usage

dviSolve(
  dvi,
  threshold = 10000,
  threshold2 = max(1, threshold/10),
  maxIncomp = 2,
  ignoreSex = FALSE,
  limit = 0,
  maxAssign = 1e+05,
  detailedOutput = FALSE,
  computeLR0 = FALSE,
  verbose = TRUE,
  debug = FALSE
)

Arguments

Details

The function roughly implements the following workflow:

• Preparation and QC

  • Consolidate data and validate input: checkDVI()

  • Generate pairings: generatePairings()

• Initial reduction

  • Detect and remove nonidentifiable missing persons: findNonidentifiable()

• Iterative reduction (repeat until stable)

  • Excluded individuals and pairings: findExcluded()

  • Undisputed matches from pairwise LRs: findUndisputed()

• AM-driven analysis: amDrivenDVI()

  • Simple families (1 missing): Summarise conflicting results

  • Complex families (>1 missing): Joint analysis + GLR

• PM-driven analysis

  • Summarise remaining victim samples.

• Output

  • Format AM and PM summaries: formatSummary()

Value

A list of data frames AM and PM summarising the results.

If detailedOutput = TRUE, the output also includes:

• LRmatrix: the LR matrix from the first call to findUndisputed()

• exclusionMAtrix the exclusion matrix from the first call to findExcluded()

• jointTables: a list of joint tables for each complex family

Examples

dviSolve(example2)
dviSolve(example2, threshold = 5, detailedOutput = TRUE, verbose = FALSE)

Description

A proof-of-concept dataset involving three missing members (child, father, grandfather) of a single family. With the given data, stepwise victim identification fails to find the correct solution, while joint identification succeeds.

Usage

example1

Format

A dviData object with the following content:

• pm: A list of 3 singletons (victims).

• am: A pedigree with three missing persons and one typed reference individual.

• missing: A vector containing the names of the missing persons.

Examples

example1
plotDVI(example1, marker = 1)

jointDVI(example1)

Description

A small DVI example with three victims, and three missing persons from two reference families

Usage

example2

Format

A dviData object with the following content:

• pm: A list of 3 singletons (victims).

• am: A list of 2 pedigrees with three missing persons and one typed reference individual.

• missing: A vector containing the names of the missing persons.

Examples

example2
plotDVI(example2, marker = 1)

jointDVI(example2)

Description

Disallow certain pairings by removing them from the list dvi$pairings of candidate pairings for a given victim sample.

Usage

excludePairing(dvi, victim, missing)

Arguments

Value

A dviData object.

Examples

# Disallow V1 = M1 in the `example2` dataset:
ex = excludePairing(example2, victim = "V1", missing = "M1")
jointDVI(ex, verbose = FALSE)

# Compare with original
jointDVI(example2, verbose = FALSE)

# The only difference is in the `pairings` slot:
ex$pairings
example2$pairings

Description

This data is based on a real case, but pedigrees have been changed and marker data simulated to preserve anonymity.

Usage

exclusionExample

Format

A dviData object with the following content:

• pm: A list of 16 singletons (male victims).

• am: A list of 15 pedigrees, each with one missing person

• missing: A vector containing the names of the 15 missing persons.

Examples

exclusionExample

Description

Given a list of candidate pairings for each victim, expand.grid.nodup() constructs the corresponding assignment table. This is similar to expand.grid(), but excludes assignments where the same missing person is used more than once. The special value "*" is treated as non-assignment and may be repeated. This is used by dviJoint() to enumerate joint assignments.

Usage

expand.grid.nodup(
  pairings = NULL,
  max = 1e+05,
  df = TRUE,
  verbose = FALSE,
  lst = NULL
)

Arguments

Value

A data frame or matrix with one row for each valid assignment.

See Also

dviGridSize(), dviJoint(), generatePairings(), expand.grid()

Examples

pairings = list(V1 = c("M1", "M2", "*"), V2 = c("M1", "M2", "*"))
expand.grid.nodup(pairings)

# Compare with expand.grid()
expand.grid(pairings)

# Dataset `example1`
pairings = generatePairings(example1)
g = expand.grid.nodup(pairings)
n = dviGridSize(pairings = pairings)
stopifnot(nrow(g) == n$size)

Description

This is a wrapper for pedFamilias::readFam() that reads Familias files with DVI information.

Usage

familias2dvir(
  famfile,
  victimPrefix = NULL,
  familyPrefix = NULL,
  refPrefix = NULL,
  missingPrefix = NULL,
  missingFormat = NULL,
  othersPrefix = NULL,
  verbose = TRUE,
  missingIdentifier = "^Missing"
)

Arguments

Details

The sex of the missing persons need to be checked as this information may not be correctly recorded in the fam file.

Value

A dviData object.

See Also

dviData(), relabelDVI()

Examples

# Family with three missing
file = system.file("extdata", "dvi-example.fam", package="dvir")

# Read file without relabelling
y = familias2dvir(file)
plotDVI(y)

# With relabelling
z = familias2dvir(file, missingFormat = "M[FAM]-[IDX]",
                   refPrefix = "ref", othersPrefix = "E")
plotDVI(z)

Description

Analysing exclusions is often an efficient way to reduce large DVI datasets. A pairing V = M is excluded if it implies (too many) genetic inconsistencies. The function findExcluded() identifies and removes (i) victim samples with too many inconsistencies against all missing persons, (ii) missing persons with too many inconsistencies against all victim samples, and (iii) inconsistent pairings among the remaining.

Usage

findExcluded(
  dvi,
  maxIncomp = 2,
  pairings = NULL,
  ignoreSex = FALSE,
  verbose = TRUE
)

exclusionMatrix(dvi, pairings = NULL, ignoreSex = FALSE)

Arguments

Details

The main calculation in findExcluded() is done by exclusionMatrix(), which records number of incompatible markers of each pairwise comparison.

Value

A list with the following entries:

• exclusionMatrix: A matrix showing the number of inconsistencies for each pair (or NA if the pairing was not considered)

• excluded: A list of three character vectors:

  • sample: victim samples excluded against all missing persons

  • missing: missing persons excluded against all victims

  • fam: families in which all missing members are excluded against all victim samples

• dviReduced: A reduced version of dvi, where the excluded elements are removed, and the pairings are updated.

• summary: A list of data frames PM and AM, summarising the excluded individuals.

See Also

findUndisputed(). See also forrel::findExclusions() for analysis of a specific pairwise comparison.

Examples

e = findExcluded(icmp)
e$summary
e$exclusionMatrix

# The exclusion matrix can also be computed directly:
exclusionMatrix(icmp)

# Inspect a particular pair: M4 vs V4
forrel::findExclusions(icmp$am, id = "M4", candidate = icmp$pm$V4)

# Plot one of the incompatible markers
plotDVI(icmp, pm = 4, marker = "D7S820")

Description

A missing person in a DVI case is nonidentifiable if they are not related to any (genotyped) reference individuals, neither directly nor through other missing persons in the family. This function identifies such individuals, and reduces the DVI dataset accordingly.

Usage

findNonidentifiable(dvi)

Arguments

Details

Two individuals are unrelated if their kinship coefficient is zero. The implementation uses ribd::kinship() to calculate all pairwise kinship coefficients.

Value

A list with the following entries:

• nonidentifiable: A character vector (possibly empty) with the names of the nonidentifiable missing persons.

• dviReduced: A reduced dviData object, where the nonidentifiable individuals are removed from the list of missing persons. If there are no nonidentifiable, this is just a copy of dvi.

• summary: A data frame summarising the findings.

Examples

# Example 1: No nonidentifiables in dataset `example1`
findNonidentifiable(example1)

# Example 2: Add nonidentifiable person "A"
amNew = example1$am[[1]] |>
  addSon(parents = c("NN", "A"))
missNew = c(example1$missing, "A")

dvi = dviData(pm = example1$pm, am = amNew, missing = missNew)
plotDVI(dvi, textAbove = c(A = "nonidentif."))

findNonidentifiable(dvi)

Description

This function uses the pairwise LR matrix to find undisputed matches between victims and missing individuals. An identification $V_i = M_j$ is called undisputed, relative to a threshold T, if the corresponding likelihood ratio $LR_{i,j} \geq T$ AND $LR_{i,j}$ is at least T times greater than all other pairwise LRs involving $V_i$ or $M_j$.

Usage

findUndisputed(
  dvi,
  pairings = NULL,
  ignoreSex = FALSE,
  threshold = 10000,
  strict = FALSE,
  limit = 0,
  nkeep = NULL,
  numCores = 1,
  keepLRmatrs = FALSE,
  verbose = TRUE
)

Arguments

Details

If the parameter strict is set to TRUE, the last criterion is replaced with the stronger requirement that all other pairwise LRs involving $V_i$ or $M_j$ must be at most 1.

Value

A list with the following entries:

• dviReduced: A reduced version of dvi, where undisputed victims/missing persons are removed, and data from undisputed victims inserted into the reference data.

• summary: A data frame summarising the undisputed matches.

• LRmatrix: Output from pairwiseLR() applied to the reduced problem.

See Also

pairwiseLR(), findExcluded()

Examples

u1 = findUndisputed(planecrash, verbose = FALSE)
u1$summary 

# With `strict = TRUE`, the match M3 = V2 goes away
u2 = findUndisputed(planecrash, strict = TRUE, verbose = FALSE)
u2$summary

# Reason: M3 has LR > 1 also against V7
u2$LRmatrix[, "M3"] |> round(2)

Description

A family with three missing persons after a fire, and one reference individual. This example is featured in the GLR paper (Egeland & Vigeland, 2024).

Usage

fire

Format

A dviData object with the following content:

• pm: A list of 3 singletons (victims).

• am: A pedigree with three missing persons and one typed reference individual.

• missing: A vector containing the names of the missing persons.

Examples

fire
plotDVI(fire, marker = 1)
dviSolve(fire, verbose = FALSE)

Description

Combines and harmonises summary tables from different DVI analyses

Usage

formatSummary(dfs, orientation = c("AM", "PM"), columns = NULL, dvi = NULL)

Arguments

Details

The default column order is controlled by orientation, which the following effect:

• AM:

  • Column order: Family, Missing, Sample, LR, GLR, Conclusion, Comment

  • Sort by: Family and Missing

• PM:

  • Column order: Sample, Missing, Family, LR, GLR, Conclusion, Comment

  • Sort by: Sample

Columns (in any of the data frames) other than these are simply ignored.

Value

A data frame.

Examples

u = findUndisputed(planecrash)
a = amDrivenDVI(u$dviReduced, threshold2 = 500)

u$summary
a$summary

formatSummary(list(u$summary, a$summary$AM))
formatSummary(list(u$summary, a$summary$PM), orientation = "PM", dvi = planecrash)

Description

Generate a list of sex-consistent pairings for each victim in a DVI problem. By default, the empty pairing (denoted *) is included for each victim.

Usage

generatePairings(dvi, includeEmpty = TRUE, ignoreSex = FALSE)

Arguments

Value

A list of character vectors. Each vector is a subset of missing, plus the character * denoting no pairing.

See Also

jointDVI()

Examples

pm = singletons(c("V1", "V2"), sex = 1:2)
          
missing = paste0("M", 1:4)
am = list(nuclearPed(children = missing[1:3]),
          nuclearPed(children = missing[4], sex = 2))

dvi = dviData(pm, am, missing)
generatePairings(dvi)

Description

Extract the marker database from a DVI dataset

Usage

getDatabase(dvi, check = TRUE, includeAttrs = FALSE)

Arguments

Value

A list of marker information.

Examples

getDatabase(example1)
getDatabase(example1, includeAttrs = TRUE)

Description

Get AM component of selected individuals

Usage

getFamily(dvi, ids)

Arguments

Value

A vector of the same length as ids, containing the family names of the ids individuals.

Examples

getFamily(example2, ids = example2$missing)

Description

Extract the names (if present) or indices of the simple reference families, i.e., the families containing exactly 1 missing person.

Usage

getSimpleFams(dvi)

Arguments

Value

A character (if dvi$am has names) or integer vector.

See Also

getFamily()

Examples

# No simple families
simple1 = getSimpleFams(example1)
stopifnot(length(simple1) == 0)

# Second family is simple
simple2 = getSimpleFams(example2)
stopifnot(simple2 == "F2")

Description

Family grave data in Kling et al. (2021) "Mass Identifications: Statistical Methods in Forensic Genetics". There are 5 female victims and 3 male victims. There is one reference family with 5 missing females and 3 missing males. There are 23 markers, no mutation model.

Usage

grave

Format

A dviData object with the following content:

• pm: A list of 8 singletons (victims).

• am: A pedigree with 8 missing persons.

• missing: A vector containing the names of the missing persons.

Examples

grave
plotDVI(grave, marker = 1)

# dviSolve(grave)

Description

A DVI dataset based on Exercise 4.9.2 in Kling et al. (2021) "Mass Identifications". The scenario concerns a helicopter accident with seven PM samples and three reference families, containing four missing persons in total.

Usage

heli

Format

A dviData object with the following content:

• pm: A list of 7 singletons (PM samples).

• am: A list of 3 reference pedigrees.

• missing: A vector containing the names of the 4 missing persons.

Details

Two features are of particular interest. First, one of the families (F2) contains two missing individuals. Second, several PM samples originate from the same individual, necessitating a preparatory step merging these samples before matching against the reference families.

Examples

heli
plotDVI(heli)

# Identify and merge matching PM samples
m = mergePM(heli$pm, threshold = 1e6, dropout = 0.1)
names(m)

heli2 = setVictims(heli, m$pmReduced)
heli2

Description

DVI dataset based loosely on the ICMP 2017 workshop material https://www.few.vu.nl/~ksn560/Block-III-PartI-KS-ISFG2017.pdf (page 18). There are 3 female victims, 2 male victims and 6 missing persons of both sexes. We have renamed the individuals and simulated data for 13 CODIS markers (see Details).

Usage

icmp

Format

A dviData object with the following content:

• pm: A list of 5 singletons (victims).

• am: A reference pedigree with 6 genotyped members and 12 missing persons.

• missing: A vector containing the names of the missing persons.

Details

The 13 markers are, in order: CSF1PO, D3S1358, D5S818,D7S820, D8S1179, D13S317, D16S539, D18S51, D21S11, FGA, TH01, TPOX, and vWA.

Source code for the simulation, and a file containing the allele frequencies, can be found in the data-raw folder of the GitHub repository: https://github.com/magnusdv/dvir.

Examples

icmp
plotDVI(icmp)

# Markers and allele frequencies
db = getDatabase(icmp)
db[1:3]

Description

Joint matching of victims and missing persons in a disaster victim identification (DVI) case, as described by Vigeland & Egeland (2021).

Usage

jointDVI(
  dvi,
  pairings = NULL,
  ignoreSex = FALSE,
  assignments = NULL,
  limit = 0,
  nkeep = NULL,
  undisputed = TRUE,
  markers = NULL,
  threshold = 10000,
  strict = FALSE,
  disableMutations = NA,
  maxAssign = 1e+05,
  numCores = 1,
  check = TRUE,
  verbose = TRUE
)

compactJointRes(jointRes, LRthresh = NULL)

Arguments

Details

NOTE: This is a legacy function. For new projects we recommend these instead:

• dviSolve() (for a complete DVI pipeline)

• dviJoint() (for fully joint analysis)

The jointDVI() function was the first implementation of a complete DVI analysis in dvir. It both manages the analysis workflow (including exclusion of impossible pairings and detection of undisputed matches) and performs the final joint analysis. As the package evolved, it became beneficial to split these two roles, resulting in the two functions above.

Value

A data frame. Each row describes an assignment of victims to missing persons, accompanied with its log likelihood, the LR compared to the null (i.e., no identifications), and the posterior corresponding to a flat prior.

The function compactJointRes() removes columns without assignments, and solutions whose LR compared with the top result is below 1/LRthresh.

References

Vigeland, MD., Egeland, T. Joint DNA-based disaster victim identification. Sci Rep 11, 13661 (2021).

See Also

pairwiseLR(), findUndisputed()

Examples

jointDVI(example2)

Description

Data used in the example in Chapter 4.8.1 in Kling et al. (2021) "Mass Identifications: Statistical Methods in Forensic Genetics". The victims are V1 and V2, both females. There is one reference family with 2 missing persons, both females. There are 21 markers, no mutation model.

Usage

KETPchap481

Format

A dviData object with the following content:

• pm: A list of 2 singletons (victims).

• am: A list of 1 pedigree.

• missing: A vector containing the names of the missing persons.

Examples

plotDVI(KETPchap481, marker = 1)

Description

Data used in last example of Chapter 4 in Kling et al. (2021) "Mass Identifications: Statistical Methods in Forensic Genetics". There are 2 female victims, 2 male victims. There are four reference families with 2 missing females and 2 missing males. There are 21 markers. An 'equal mutation mode with rate 0.005 is specified.

Usage

KETPchap484

Format

A dviData object with the following content:

• pm: A list of 4 singletons (victims).

• am: A list of 3 pedigrees.

• missing: A vector containing the names of the missing persons.

Examples

KETPchap484

plotDVI(KETPchap484, nrowPM = 4)

Description

Data used in Exercise 4.9.7 in Kling et al. (2021) "Mass Identifications: Statistical Methods in Forensic Genetics". There are 3 female victims and 3 reference families with 3 missing females. There are 23 markers, equal mutation model, rate 0.001.

Usage

KETPexer497

Format

A dviData object with the following content:

• pm: A list of 3 singletons (victims).

• am: A list of 3 pedigrees.

• missing: A vector containing the names of the missing persons.

Examples

plotDVI(KETPexer497, nrowPM = 3)

Description

Data used in Exercise 4.9.8 in Kling et al. (2021) "Mass Identifications: Statistical Methods in Forensic Genetics". There are 2 female victims and 1 male. There is one reference family with 2 missing females and one missing male. There are 16 markers, equal mutation model, rate 0.001.

Usage

KETPexer498

Format

A dviData object with the following content:

• pm: A list of 3 singletons (victims).

• am: A list of 1 pedigree.

• missing: A vector containing the names of the missing persons.

Examples

plotDVI(KETPexer498)

Description

Computes pairwise direct-match LRs for post-mortem samples, identifies groups of matching samples, and reduces each group to a single profile.

Usage

mergePM(
  pm,
  threshold = 10000,
  method = c("combine", "first", "mostcomplete"),
  names = c("combine", "first", "mostcomplete"),
  dropout = 0,
  dropin = 0,
  typingError = 0,
  ignoreSex = FALSE,
  markerwise = FALSE,
  verbose = TRUE
)

Arguments

Details

See directMatch() for details and references for the dropout, drop-in and typing-error model.

Groups are defined as connected components of pairs whose LR is at least threshold. Thus, samples may belong to the same group even if their pairwise LR is below the threshold, provided they are connected through other samples.

The available merging methods are:

• "combine": Combine the observed alleles across all samples in the group. With dropout, discrepancies compatible with allelic dropout are allowed. Without dropout, complete genotypes must agree. Markers that cannot be combined are set to missing and reported in problems.

• "first": Retain the first sample in each group, according to input order.

• "mostcomplete": Retain the sample with the most non-missing genotypes.

The names of the resulting clusters are controlled by names: "first" uses the first sample, "mostcomplete" the most complete sample, while "combine" joins all sample names with "_".

Value

A list with the following entries:

• groups: The groups of matching samples (including singleton groups).

• LRmat: A symmetric matrix with zero diagonal, containing all pairwise direct-match LRs.

• LRmarker: If markerwise = TRUE, a sample x sample x marker array of LRs, with zero diagonals. Otherwise NULL.

• nonmissing: The number of non-missing genotypes for each sample.

• pmReduced: The reduced list of PM samples.

• problems: For method = "combine", a named list of markers that could not be combined and were set to missing. Empty otherwise.

See Also

directMatch().

Examples

# PM data from helicopter dataset
pm = heli$pm

merge = mergePM(pm)

# Inspect the results
merge$groups
merge$LRmat
merge$nonmissing
merge$pmReduced
merge$problems

# Marker-wise pairwise LRs
lrs = mergePM(pm, markerwise = TRUE, dropout = 0.01)$LRmarker
g = getGenotypes(pm, ids = c("PM1", "PM4"))
data.frame(t(g), LR = lrs["PM1", "PM4", ])

Description

Calculates the total number of assignments, i.e., the different ways the victims can be paired with the missing persons while respecting sex. Note that in practice, the number of assignments considered in a joint DVI analysis is usually much smaller than this, due to reductions in preliminary steps. See dviGridSize() for a more refined version.

Usage

ncomb(nVfemales, nMPfemales, nVmales, nMPmales)

Arguments

Value

The total number of possible assignments.

See Also

dviGridSize()

Examples

# Example
m1 = ncomb(5,5,5,5)

# Example: 3 male victims; 2 male missing persons.
# The number of a priori possible assignments is
m1 = ncomb(0,0,3,2) # 13


# Compare with the complete list of assignments
m2 = expand.grid.nodup(list(V1 = c("*", "M1", "M2"),
                            V2 = c("*", "M1", "M2"),
                            V3 = c("*", "M1", "M2")))
stopifnot(m1 == nrow(m2))

Description

For a given DVI problem, compute the matrix consisting of pairwise likelihood ratios $LR_{i,j}$ comparing $V_i = M_j$ to the null. The output may be reduced by specifying arguments limit or nkeep.

Usage

pairwiseLR(
  dvi,
  pairings = NULL,
  ignoreSex = FALSE,
  limit = 0,
  nkeep = NULL,
  check = FALSE,
  numCores = 1,
  verbose = FALSE
)

Arguments

Value

A list with 3 elements:

• LRmatrix: A matrix containing the pairwise LR values.

• LRlist: A list of numerical vectors, containing the pairwise LRs in list format.

• pairings: A reduced version of the input pairings, keeping only entries with corresponding LR >= limit. For the default case limit = 0 a strict inequality is used, i.e., LR > 0.

Examples

pairwiseLR(example1, verbose = TRUE)

Description

A simulated dataset based on Exercise 3.3 in Egeland et al. "Relationship Inference with Familias and R" (2015).

Usage

planecrash

Format

A dviData object with the following content:

• pm: A list of 8 female singletons (victims).

• am: A list of 5 pedigrees, each with one missing member and one genotyped member.

• missing: A vector containing the names of the missing persons.

Details

The 15 markers are CSF1PO, D13S317, D16S539, D18S51, D21S11, D3S1358, D5S818, D7S820, D8S1179, FGA, PENTA_D, PENTA_E, TH01, TPOX, and VWA.

Source code for the simulation, and a file containing the allele frequencies, can be found in the data-raw folder of the GitHub repository: https://github.com/magnusdv/dvir.

Examples

planecrash
plotDVI(planecrash)

# Markers and allele frequencies
db = getDatabase(planecrash)
db[1:3]

Description

Plot a DVI problem

Usage

plotDVI(
  dvi,
  pm = TRUE,
  am = TRUE,
  style = 1,
  famnames = NA,
  hatched = typedMembers,
  frames = TRUE,
  titles = c("PM", "AM"),
  cex = NA,
  cex.titles = NA,
  col = 1,
  lwd = 1,
  fill = NA,
  carrier = NULL,
  widths = NULL,
  heights = NULL,
  nrowPM = NA,
  nrowAM = NA,
  ncolAM = NA,
  dev.height = NULL,
  dev.width = NULL,
  newdev = !is.null(c(dev.height, dev.width)),
  ...
)

Arguments

Examples

plotDVI(example2)

# Override default layout
plotDVI(example2, nrowPM = 1, ncolAM = 1)

# Subset
plotDVI(example2, pm = 1:2, am = 1, titles = c("PM (1-2)", "AM (1)"))

# AM only
plotDVI(example2, pm = FALSE, titles = "AM families")

# Further plot options
plotDVI(example2, frames = FALSE, marker = 1, cex = 1.2, nrowPM = 3, nrowAM = 2,
  textAnnot = list(inside = list(c(M1 = "?", M2 = "?", M3 = "?"), cex = 1.5)))

Description

A version of plotDVI() tailor-made to visualise identified individuals, for example as reported by jointDVI().

Usage

plotSolution(dvi, assignment, k = 1, format = "[S]=[M]", ...)

Arguments

Value

NULL.

Examples

res = jointDVI(example2, verbose = FALSE)

plotSolution(example2, res)

# With line break in labels
plotSolution(example2, res, format = "[M]=\n[S]")

# With genotypes for marker 1
plotSolution(example2, res, marker = 1)

# Non-optimal solutions
plotSolution(example2, res, k = 2, pm = FALSE)
plotSolution(example2, res, k = 2, cex = 1.3)

Description

Plot undisputed identifications

Usage

plotUndisputed(dvi, undisputed, ...)

Arguments

See Also

findUndisputed(), plotSolution()

Examples

# Example
res = findUndisputed(example2, threshold = 2, verbose = FALSE)
u = res$summary
plotUndisputed(example2, u, marker = 1)

Description

Relabel the individuals and families in a DVI dataset.

Usage

relabelDVI(
  dvi,
  victims = NULL,
  victimPrefix = NULL,
  familyPrefix = NULL,
  refs = NULL,
  refPrefix = NULL,
  missingPrefix = NULL,
  missingFormat = NULL,
  othersPrefix = NULL
)

Arguments

Value

A dviData() object.

Examples

# Builtin dataset `example2`
relabelDVI(example2,
           victimPrefix  = "vic",
           familyPrefix  = "fam",
           refPrefix     = "ref",
           missingPrefix = "mp")

# Family-wise labelling of missing persons
relabelDVI(example2, missingFormat = "M[FAM]-[IDX]")
relabelDVI(example2, missingFormat = "M[IDX] (F[FAM])")
relabelDVI(example2, missingFormat = "fam[FAM].m[IDX]")

Description

Performs a sequential matching procedure based on the pairwise LR matrix. In each step the pairing corresponding to the highest LR is selected and included as a match if the LR exceeds the given threshold. By default, (updateLR = TRUE) the pairwise LRs are recomputed in each step after including the data from the identified sample.

Usage

sequentialDVI(
  dvi,
  updateLR = TRUE,
  threshold = 1,
  check = TRUE,
  verbose = TRUE,
  debug = FALSE
)

Arguments

Details

If, at any point, the highest LR is obtained by more than one pairing, the process branches off and produces multiple solutions. (See Value.)

Value

A list with two elements:

• matches: A single assignment vector, or (if multiple branches) a data frame where each row is an assignment vector.

• details: A data frame (or a list of data frames, if multiple branches) including the LR of each identification in the order they were made.

Examples

# Without LR updates
sequentialDVI(example1, updateLR = FALSE)

# With LR updates (default). Note two branches!
r = sequentialDVI(example1)

# Plot the two solutions
plotSolution(example1, r$matches, k = 1)
plotSolution(example1, r$matches, k = 2)

# Add `debug = T` to see the LR matrix in each step
sequentialDVI(example1, debug = TRUE)

# The output of can be fed into `jointDVI()`:
jointDVI(example1, assignments = r$matches)

Description

A fast alternative to pedtools::setMarkers() for prepared allele matrices. All pedigree components use the same alleles and frequencies, and untyped individuals receive missing genotypes.

Usage

setMarkersFromMatrix(x, alleleMatrix = NULL, loci = NULL)

Arguments

Value

The input pedigrees with markers attached, preserving list structure.

Examples

peds = list(nuclearPed(), singleton("NN"))
db = forrel::NorwegianFrequencies[1:2]
ids = c("3", "NN")

# Simulate profiles and extract alleles
x = forrel::profileSim(peds, ids = ids, markers = db, seed = 1)
a = getAlleles(x, ids = ids)
loc = getLocusAttributes(x)

y1 = setMarkersFromMatrix(x, a)
y2 = setMarkersFromMatrix(x, a, loci = loc)

stopifnot(identical(x, y2))

# Note the difference:
afreq(y1, 1)
afreq(y2, 1)

Description

Manually set one or several identifications in a DVI dataset. Typically, these are obtained by external means, e.g., fingerprints, dental records etc.

Usage

setPairing(
  dvi,
  match = NULL,
  victim = NULL,
  missing = NULL,
  Conclusion = "Provided",
  Comment = "",
  verbose = TRUE
)

Arguments

Details

The command setPairing(dvi, c("V" = "M")) does the following:

• Transfer the data of victim "V" to the individual "M" in the appropriate reference family

• Remove "M" from the list of missing persons

• Remove "V" from the list of victim samples

• Update the list of pairings

Value

A list with the following entries:

• dviReduced: The new dviData object, as described in Details

• summary: A data frame summarising the identifications

Examples

x = setPairing(example2, match = c("V3" = "M2"))
x$dviReduced
x$summary

# Alternative syntax, using `victim` and `missing`
y = setPairing(planecrash, victim = c("V4", "V5"), missing = c("M4", "M5"),
           Conclusion = "External evidence", Comment = "Dental")
y$dviReduced
y$summary

Description

Convenience functions for replacing or adding victim samples in an existing dviData() object. These functions should generally be preferred over direct manipulation of the pm component, as they ensure consistency and recompute the internal pairings object.

Usage

setVictims(dvi, vics)

addVictims(dvi, vics)

Arguments

Details

setVictims() replaces all existing victim samples, while addVictims() retains the existing samples and appends new ones.

Value

A modified dviData() object.

Examples

# Add a victim
addVictims(example1, singleton("V4"))

# Replace the PM data
setVictims(example1, singleton("V4"))

Description

Extract a subset of a DVI dataset

Usage

subsetDVI(
  dvi,
  pm = NULL,
  am = NULL,
  missing = NULL,
  removeUnpairedPM = TRUE,
  verbose = TRUE
)

Arguments

Value

A dviData object.

Examples

subsetDVI(example2, pm = 1:2) |> plotDVI()
subsetDVI(example2, pm = "V1", am = 1) |> plotDVI()
subsetDVI(example2, missing = "M3") |> plotDVI()

Description

This function switches the roles of victims and missing persons in a table of assignments, from PM-oriented (victims as column names) to AM-oriented (missing persons as column names), and vice versa. In both versions, each row describes the same assignment vector.

Usage

swapOrientation(df, from = NULL, to = NULL)

Arguments

Value

A data frame with nrow(df) rows and length(to) columns.

Examples

df = example1 |> generatePairings() |> expand.grid.nodup()
df
swapOrientation(df)

# Swap is idempotent
stopifnot(identical(swapOrientation(swapOrientation(df)), df))

Description

A toy DVI dataset illustrating various forms of undecidability due to symmetries in the solutions.

Usage

symmetricSibs

Format

A dviData object with the following content:

• pm: A list of 5 singletons (male victims).

• am: A list of 3 pedigrees

• missing: A character vector of length 5, naming the missing persons.

Examples

symmetricSibs

Description

Convenience wrapper for pedFamilias::writeFam() with dvi parameter set to TRUE.

Usage

writeFamDVI(
  x,
  famfile = "dvi.fam",
  params = NULL,
  dbOnly = FALSE,
  openFam = FALSE,
  FamiliasPath = NULL,
  verbose = TRUE
)

Arguments

Value

The file name is returned invisibly.

See Also

familias2dvir(), pedFamilias::writeFam()

Examples

writeFamDVI(planecrash, tempfile(fileext = ".fam"))