per_marker_kl: Per-marker bidirectional Kullback-Leibler divergence and...

In mispitools: Missing Person Identification Tools

Per-marker bidirectional Kullback-Leibler divergence and expected log10 LR

Description

Computes, for a single marker model, the expected log10 likelihood ratio under both hypotheses and the bidirectional Kullback-Leibler divergence between the joint H1 and H2 distributions over pedigree typings. Drives the C++ engine introduced in F2 / F3.1; returns the same numerical content as the internal reference engine to bit-equivalent precision.

Boundary convention follows the reference engine:

• P_H1(g) > 0 and P_H2(g) = 0 contribute +Inf to kl_h1_to_h2 and e_log10_lr_h1.

• P_H1(g) = 0 and P_H2(g) > 0 contribute +Inf to kl_h2_to_h1 and -Inf to e_log10_lr_h2.

• States with P_H1 = P_H2 = 0 are skipped (already filtered by the joint engine).

Under mutation = "none" the H2 distribution typically spans Mendelian-incompatible states with zero mass under H1, so kl_h2_to_h1 = +Inf. The ⁠abs_cont_violations_*⁠ and ⁠mass_violations_*⁠ columns quantify how much probability mass falls on violating states in each direction.

Usage

per_marker_kl(model, poi = NULL)

Arguments

model	A marker_model object (see marker_model()).
poi	Optional character scalar naming the person of interest in the pedigree. When NULL (default), the engine resolves the POI by picking the last untyped non-founder, falling back to the last non-founder, and finally to the last member.

Value

A one-row data.frame with columns

marker

Marker identifier (character).

e_log10_lr_h1

Expected log10(LR) under H1.

e_log10_lr_h2

Expected log10(LR) under H2.

kl_h1_to_h2

KL(H1 || H2) in nats.

kl_h2_to_h1

KL(H2 || H1) in nats.

abs_cont_violations_h1

Number of joint states with positive H2 mass but zero H1 mass (integer).

abs_cont_violations_h2

Number of joint states with positive H1 mass but zero H2 mass (integer).

mass_violations_h1

Total H2 mass on states violating H1 absolute continuity (numeric).

mass_violations_h2

Total H1 mass on states violating H2 absolute continuity (numeric).

Attribute "poi" records the resolved POI identifier.

See Also

marker_model(), per_marker_kl_profile().

Examples

if (requireNamespace("pedtools", quietly = TRUE)) {
  ped <- pedtools::nuclearPed(1)
  freqs <- c("a" = 0.3, "b" = 0.5, "c" = 0.2)
  mm <- marker_model(ped, "M1", freqs,
                     mutation = list(model = "equal", rate = 0.005))
  per_marker_kl(mm)
}

mispitools documentation built on Aug. 26, 2026, 1:08 a.m.