Documentation / Family Analysis / Trio Quality Control

Trio Quality Control with PLINK IBD Analysis

Trio interpretation depends on the declared proband, mother, and father labels matching the biological relationships represented in the sequencing data. Folklore checks those relationships before relying on the trio for inheritance analysis.

The check estimates pairwise identity by descent with PLINK 1.9. It can flag relationship patterns compatible with a sample swap, duplicate sample, or related parents. It does not establish the cause of an unexpected result.

Why This Check Comes First

De novo detection, parental-origin phasing, and segregation scoring all depend on correctly assigned family roles. A critical identity alert makes those downstream inheritance results unreliable even when the variant-level computations completed successfully.

Input and PLINK Preparation

The QC stage reads the normalized joint multi-sample VCF and maps each VCF sample identifier to proband, mother, or father. Sample identifiers must match the joint VCF columns exactly.

Before pairwise IBD estimation, PLINK converts the VCF to binary format. Half-calls are treated as missing, only strictly biallelic variants are retained, variants below a minor-allele frequency of 0.05 are removed, and sites with more than 5 percent missing genotypes are excluded.

Pairwise IBD Output

Field	Meaning
PI_HAT	Estimated proportion of alleles shared identical by descent across the pair.
Z0	Estimated probability that the pair shares zero alleles identical by descent.
Z1	Estimated probability that the pair shares one allele identical by descent.
Z2	Estimated probability that the pair shares two alleles identical by descent.

PI_HAT is the primary threshold value used by the current alert rules. Z0, Z1, and Z2 remain visible for review and audit of the pairwise relationship pattern.

Current Alert Rules

Declared Pair	Condition	Alert	Severity	Handling
Parent and proband	PI_HAT < 0.40	Sample swap	Critical	QC does not pass. Inheritance results should not drive interpretation until sample identity or pedigree labelling is resolved.
Parent and proband	PI_HAT > 0.70	Duplicate sample	Warning	Possible duplicate sample or unusually high relatedness. The warning requires review but does not by itself set QC passed to false.
Mother and father	PI_HAT > 0.125	Consanguinity	Warning	The declared parents show third-degree-or-closer relatedness under the configured threshold. The family context should be reviewed.

Expected Parent-Child Range

A declared parent-proband pair with PI_HAT from 0.40 through 0.70 does not trigger an alert in the current implementation. The interval is an operational QC range, not a statement that every value inside it represents the same biological relationship with equal certainty.

PI_HAT alone does not reliably distinguish every relationship class. Full siblings can also cluster near 0.50, and unusual family structure or population context can alter the observed pattern. The declared pedigree and the complete IBD profile still require review.

Critical and Warning States

The trio-level passed field is false only when at least one critical alert is present. In the current implementation, a low parent-child PI_HAT creates that critical state.

Duplicate-sample and consanguinity alerts are warnings. They remain visible in the QC record, but a warning alone does not change passed to false. This distinction should not be read as clinical clearance; warning findings still require review.

Skipped Check Versus Passed Check

The QC contract records whether IBD analysis was performed. A legacy or incomplete run without a joint VCF can carry ibd_check_performed=false, reason_skipped=no_joint_vcf, and passed=true.

In that state, passed does not mean that biological relationships were confirmed. It means that no critical PLINK result was produced because the IBD check did not run. The performed flag and skip reason must be read with the passed field.

Execution Failure

A PLINK timeout, malformed output, missing required output column, missing input VCF, or failed subprocess is not converted into a neutral QC result. The trio pipeline fails at the sample_qc stage and records the failure for recovery.

This separates an unavailable computation from an evaluated trio that produced no critical alerts.

Clinical Review Boundary

A QC alert identifies a relationship pattern that needs investigation. It does not prove a sample swap, duplicate, or specific degree of consanguinity. Resolution can require laboratory records, sample identifiers, pedigree confirmation, and repeat or orthogonal testing.

Recorded QC Data

Folklore stores the pairwise IBD values, alerts, pass state, critical-alert flag, PLINK version, and optional skip reason in the trio QC summary. The same summary is written to the versioned trio_qc.json artifact with its generation time and family identifier.

The family workspace displays the pair table in the Members section and places critical sample-integrity alerts above the family result tabs so that the warning remains visible outside the QC table.