familias_trajectory: Belief trajectory metrics from a...

In mispitools: Missing Person Identification Tools

Belief trajectory metrics from a Familias::FamiliasPosterior result

Description

Convenience wrapper that extracts the per-marker likelihood ratios from the result list returned by Familias::FamiliasPosterior and computes the full belief-trajectory machinery of Marsico & Egeland (in preparation): the binary belief trajectory, the trajectory metrics (entropy, per-step KL divergence, total-variation path length, and the three concentration measures), the signed concentration index C_W^+ for fragility of inclusions, and the per-marker leave-one-out analysis.

Usage

familias_trajectory(familias_result, test_pedigree = 2, ref_pedigree = 1)

Arguments

familias_result	A list with the structure returned by Familias::FamiliasPosterior. Must contain a numeric matrix named LRperMarker with rows indexing markers and columns indexing candidate pedigrees. Column ref_pedigree is assumed to contain the reference hypothesis (typically all ones after normalization).
test_pedigree	Integer or character. Index or name of the alternative pedigree whose per-marker LRs (as a ratio against the reference pedigree) should be used to build the belief trajectory. Defaults to 2 (i.e., the first non-reference pedigree), which is the standard arrangement in two-pedigree comparisons.
ref_pedigree	Integer or character. Index or name of the reference pedigree. Defaults to 1. Used for sanity checks only; the actual LR-per-marker values for test_pedigree are taken from familias_result$LRperMarker directly because FamiliasPosterior already normalizes the matrix against the reference column.

Details

Familias::FamiliasPosterior computes posterior probabilities of candidate pedigrees given DNA evidence. Its return value includes a LRperMarker matrix of per-locus likelihood ratios already normalized against the reference pedigree. This wrapper simply selects the relevant column and hands the resulting per-marker LR vector to the Belief Dynamics trajectory machinery, so that a user of Familias can obtain trajectory metrics and fragility diagnostics in a single function call without manually constructing the per-marker sequence.

If Familias is not installed, this function does not depend on it — the input is expected to be a list with the structure described above, which can equally well be constructed by hand for testing or from other sources (e.g., forrel::missingPersonLR).

Value

A list with components:

lrs

Named numeric vector of per-marker likelihood ratios for the chosen test pedigree against the reference.

trajectory

Data frame from binary_belief_trajectory with the posterior at each step, cumulative log-LR, and the per-step log-LR.

metrics

List from trajectory_metrics with entropy, per-step KL divergence, cumulative KL from prior, per-step total-variation, path length, and the three concentration measures.

concentration_positive

Numeric scalar. The signed concentration index C_W^+ restricted to positive (supporting) per-marker contributions; the primary fragility diagnostic of the Belief Dynamics framework.

leave_one_out

Data frame from leave_one_out giving the per-marker fragility table.

References

Marsico, F. L. & Egeland, T. (in preparation). Belief dynamics during the investigative process. Egeland, T., Mostad, P. & Simonsson, I. (2015). Relationship inference with Familias and R. Academic Press.

See Also

binary_belief_trajectory, trajectory_metrics, concentration_index_positive, leave_one_out.

Examples

# Synthetic Familias-like result with 6 markers and 2 pedigrees
fam <- list(
  LRperMarker = matrix(
    c(1, 1, 1, 1, 1, 1,          # reference pedigree, col 1
      5.2, 1.8, 12.0, 3.1, 0.8, 2.7), # test pedigree,     col 2
    nrow = 6, ncol = 2,
    dimnames = list(c("D3S1358", "TH01", "D21S11",
                      "D18S51",  "CSF", "vWA"),
                    c("Unrelated", "GrandparentGrandchild"))
  )
)
result <- familias_trajectory(fam, test_pedigree = 2)
result$concentration_positive
result$leave_one_out

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