#forensicgenetics

import "@jennifer/forensicgenetics/" as forensics;

The entry module: profiles, reference frequencies, match probability and mixtures. Errors are Error{kind: "forensicgenetics"}.

#Constants

#Types

def struct LocusFrequencies {
    locus as string,
    n as int,                             # individuals typed
    alleles as map of string to float     # allele label -> published frequency
};

def struct FrequencyDb {
    name as string,
    loci as map of string to LocusFrequencies
};

def struct Genotype {
    locus as string,
    a as string,                          # canonically ordered pair
    b as string
};

def struct Profile {
    id as string,
    loci as map of string to Genotype
};

def struct Mixture {
    id as string,
    loci as map of string to list of string
};

#Allele labels

#Frequency database

The generic, vendor-independent type. This module reads no published format; a reader deck converts one into a FrequencyDb (see @mplx/strider).

withLocus rejects an empty locus name, a negative n, a frequency outside (0, 1], or allele frequencies summing past MAX_FREQUENCY_SUM. A locus may legitimately list only some of its alleles, so a sum below 1 is fine; a sum meaningfully above it is a misread table, and accepting one yields genotype "probabilities" greater than 1. Every lookup throws with a message naming the missing locus.

combineFrequencies throws on an empty list, when the inputs share no locus, or when a shared locus has no sample size anywhere; it keeps only the loci every input covers, so check loci on the result to see what survived. Pooling describes one merged population, and merging populations whose frequencies differ biases the match probability downwards - the Wahlund effect. For an uncertain population use randomMatchProbabilityAcross instead; see Limitations.

#Genotypes and profiles

#Match probability

theta must be in [0, 1). All five panel functions throw on an empty profile or on a locus the database does not cover - they do not silently drop loci. See Match probability.

The Across pair is for a donor whose population is uncertain: weights are the prior probabilities that the donor came from each population, one per entry of dbs, and must be non-negative and sum to 1. Every table must cover every locus in the profile, and theta is applied within each population. They throw on an empty list, a length mismatch, a negative weight, or weights that do not sum to 1; matchLikelihoodRatioAcross also throws if the weighted probability is zero. Averaging the answer this way is not the same as pooling the tables with combineFrequencies, which biases it - see Reference frequency data.

#Mixtures

None of these take a theta; see Theta.

#Errors

Error{kind: "forensicgenetics"} for: an unknown locus, an unknown frequency format, an empty or duplicated locus name, a frequency outside (0, 1], a locus whose frequencies sum past MAX_FREQUENCY_SUM, an empty allele label, a theta outside [0, 1), an empty profile or mixture locus, a profile and mixture sharing no locus, a non-numeric allele passed to alleleValue, and a locus with neither a frequency nor a sample size to floor with.