PedNet 2.0.0__py3-none-any.whl

pednet/__init__.py

@@ -0,0 +1,24 @@
+"""PedNet: pedigrees as graphs. A pedigree is a directed acyclic graph, and PedNet analyses its structure (graph),
+the pattern of affected people in it (features), and, with the graph as a Bayesian network of genotypes, the mode
+of inheritance (inheritance) and the co-segregation of candidate variants (segregation)."""
+from .features import (classify_by_metrics, classify_by_patterns, network_metrics, pattern_features,
+                       segregation_network_score)
+from .genotypes import read_genotype_table, read_vcf
+from .graph import (inbreeding, kinship, kinship_matrix, loops, mating_graph, moral_graph, pedigree_graph,
+                    relationship)
+from .inheritance import InheritanceResult, ModeEvidence, infer_mode, infer_shared_mode
+from .models import MODE_NAMES, MODES, Model
+from .pedigree import Pedigree, PedigreeError, Person, pedigree_from_rows, read_ped, write_ped
+from .segregation import (CombinedScore, Variant, VariantScore, evidence_strength, rank_variants,
+                          rank_variants_across)
+
+__version__ = '2.0.0'
+
+__all__ = [
+    'pedigree_graph', 'mating_graph', 'moral_graph', 'loops', 'kinship', 'kinship_matrix', 'inbreeding',
+    'relationship', 'network_metrics', 'pattern_features', 'classify_by_metrics', 'classify_by_patterns',
+    'segregation_network_score', 'infer_mode', 'infer_shared_mode', 'rank_variants', 'rank_variants_across',
+    'evidence_strength', 'read_ped', 'write_ped', 'pedigree_from_rows', 'read_vcf', 'read_genotype_table', 'Pedigree',
+    'Person', 'PedigreeError', 'Variant', 'VariantScore', 'CombinedScore', 'InheritanceResult', 'ModeEvidence',
+    'Model', 'MODES', 'MODE_NAMES', '__version__',
+]

pednet/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

pednet/_trained.py

@@ -0,0 +1,29 @@
+"""
+What the graph classifiers learnt from simulated families: written by benchmarks/train_classifiers.py
+(--families 1000 --seed 2026), so not to be edited by hand.
+"""
+import numpy as np
+
+# the original PedNet's metric classifier: for each metric kept, (threshold, the mode above it, AUC)
+METRIC_THRESHOLDS = {
+    'ratio_aff_parent': (0.1111111111111111, 'AD', 0.9012114999999999),
+    'gen_cov': (0.6, 'AD', 0.9238780000000001),
+}
+
+# the pattern classifier: a multinomial logistic regression on the standardised pattern features
+PATTERN_MODES = ('AD', 'AR', 'XLR', 'XLD')
+PATTERN_FEATURES = ('affected_share', 'affected_generations', 'vertical', 'skipped', 'male_to_male', 'father_daughters', 'father_sons', 'mother_sons', 'mother_daughters', 'male_share', 'sibship_share', 'consanguineous', 'x_kinship_ratio', 'log_affected', 'generations')
+PATTERN_MEAN = [0.2288667395449686, 0.5803541666666686, 0.40144131520243254, 0.5167159261451486, 0.10125, 0.47170645118770116, 0.3994372391497424, 0.46893794820859014, 0.46218275197025294, 0.5515335644005488, 0.3258036546985266, 0.162, 1.6527039199006657, 1.371156159023878, 3.602]
+PATTERN_SCALE = [0.15691928293100238, 0.2662495688246373, 0.2996787021857291, 0.3131688349901684, 0.30165947275032157, 0.17532353722532326, 0.1624887568864363, 0.14217934096949675, 0.13727154479049042, 0.2453081607271272, 0.19799178472520745, 0.3684508108282698, 0.9223493348315648, 0.4281489057315073, 0.9915119767304735]
+PATTERN_WEIGHTS = [
+    [0.8092720131088182, 0.18992408312039233, 0.6857974684471309, 0.6519792503432646, -0.2504322379566621, 0.28036090058000485, -0.2083172247494853, 0.12851272377005746, -0.058472181775463594, -0.040368521292830264, -0.35714127586906425, 0.057240308641926925, -0.2113480362407416, -0.4682721888126473, 0.1528224133528207, 0.35448056670608313],
+    [-0.1670559522948906, -0.2414898621455553, -1.4588708403730801, -0.445048041335051, 0.29944889519867535, 0.3438390037250986, -0.13499945353916662, 0.4420631849699804, 0.057159195992491266, 0.2632533430722387, -0.5093368709639541, -0.009309500402416602, 0.10889788078714148, -0.20239079341476177, 0.08182431805373414, -0.3440431171243752],
+    [-1.020260535228255, -0.017737476951062557, -0.050290987569196956, -0.5441934340954122, 0.2869424333194238, 0.08099393226349302, -0.0627603008747609, -0.30717192437573515, -0.0647562773984802, -0.029521438535975924, 2.0010873461292147, -0.27222116287871, 0.01615158411027784, 0.25896598161465584, -0.21357803694818064, -0.2752612154112168],
+    [0.37804506628606654, 0.06930325597634003, 0.8233643594969503, 0.33726222508441567, -0.33595909055899875, -0.7051938365702919, 0.40607697916318464, -0.26340398436412177, 0.0660692631826541, -0.19336338324366237, -1.1346091992974519, 0.22429035463922664, 0.08629857134284158, 0.4116970006128527, -0.021068694459017993, 0.2648237658292406],
+]
+
+
+def pattern_classifier():
+    from .features import PatternClassifier
+    return PatternClassifier(PATTERN_MODES, PATTERN_FEATURES, np.array(PATTERN_MEAN), np.array(PATTERN_SCALE),
+                             np.array(PATTERN_WEIGHTS))

pednet/cli.py

@@ -0,0 +1,378 @@
+"""The pednet command:
+
+    pednet graph FAMILY.ped                the pedigree as a graph: its structure, loops, kinship and patterns
+    pednet mode FAMILY.ped                 the mode of inheritance
+    pednet rank FAMILY.ped VARIANTS.vcf    candidate variants ranked by co-segregation
+    pednet check FAMILY.ped                what PedNet makes of a PED file
+"""
+import argparse
+import csv
+import os
+import sys
+from typing import List, Optional
+
+from . import __version__
+from . import graph as pedgraph
+from .features import classify_by_metrics, classify_by_patterns, network_metrics, pattern_features
+from .genotypes import read_genotype_table, read_vcf, vcf_samples
+from .inheritance import DEFAULT_PENETRANCE, DEFAULT_PHENOCOPY, infer_mode, infer_shared_mode
+from .models import MODES
+from .pedigree import PedigreeError, read_ped
+from .segregation import DEFAULT_ERROR_RATE, MIN_VARIANT_FREQUENCY, rank_variants, rank_variants_across
+
+
+def _floats(text: str) -> List[float]:
+    try:
+        return [float(x) for x in text.replace(',', ' ').split()]
+    except ValueError:
+        raise argparse.ArgumentTypeError(f'expected numbers separated by commas, not {text!r}')
+
+
+def _families(args):
+    families = read_ped(args.ped, args.family)
+    if not families:
+        raise PedigreeError(f'There are no people in {args.ped}')
+    if getattr(args, 'proband', None) and len(families) > 1:
+        raise PedigreeError('--proband needs --family, since the PED file has more than one family')
+    return families
+
+
+def _common(parser):
+    parser.add_argument('ped', help='the PED file')
+    parser.add_argument('--family', help='only this family (by default every family in the file)')
+    parser.add_argument('--proband', help='the person through whom the family was found (by default each affected '
+                                          'person in turn)')
+    parser.add_argument('--modes', default=','.join(MODES),
+                        help='the modes of inheritance to weigh up, separated by commas (default: all four)')
+    parser.add_argument('--penetrance', type=_floats, default=list(DEFAULT_PENETRANCE),
+                        help='the penetrance, or several to average over (default: 0.6,0.8,0.95,0.99)')
+    parser.add_argument('--phenocopy', type=float, default=DEFAULT_PHENOCOPY,
+                        help=f'the chance of being affected without the disease genotype (default: {DEFAULT_PHENOCOPY})')
+
+
+def _write_tsv(rows, handle):
+    fields = []
+    for row in rows:
+        fields.extend(k for k in row if k not in fields)
+    writer = csv.DictWriter(handle, fieldnames=fields or ['candidate'], delimiter='\t', lineterminator='\n')
+    writer.writeheader()
+    writer.writerows(rows)
+
+
+def _mode(args) -> int:
+    families = _families(args)
+    if args.method != 'likelihood':
+        if args.together:
+            raise ValueError('--together works with the likelihood method only')
+        return _mode_by_graph(args, families)
+    if args.together:
+        results = [infer_shared_mode(families, args.modes, args.penetrance, phenocopy=args.phenocopy,
+                                     threshold=args.threshold)]
+    else:
+        results = [infer_mode(pedigree, args.modes, args.penetrance, phenocopy=args.phenocopy, proband=args.proband,
+                              threshold=args.threshold) for pedigree in families.values()]
+    if args.tsv:
+        _write_tsv([row for r in results for row in r.table()], sys.stdout)
+        return 0
+    for result in results:
+        print(result)
+        print()
+    return 0
+
+
+def _mode_by_graph(args, families) -> int:
+    unused = [option for option, given in (
+        ('--proband', args.proband is not None), ('--modes', args.modes != ','.join(MODES)),
+        ('--penetrance', list(args.penetrance) != list(DEFAULT_PENETRANCE)),
+        ('--phenocopy', args.phenocopy != DEFAULT_PHENOCOPY),
+        ('--threshold', args.method == 'metrics' and args.threshold != 0.8)) if given]
+    if unused:
+        listed = unused[0] if len(unused) == 1 else ', '.join(unused[:-1]) + ' and ' + unused[-1]
+        classifier = 'pattern classifier' if args.method == 'patterns' else 'metric classifier'
+        print(f'note: the {classifier} learnt from simulated families and takes no account of {listed}, which '
+              'the likelihood method uses', file=sys.stderr)
+    rows = []
+    for name, pedigree in families.items():
+        if args.method == 'patterns':
+            result = classify_by_patterns(pedigree, threshold=args.threshold)
+            rows.extend({'family': name, 'mode': m, 'probability': p} for m, p in result.probabilities.items())
+            text = str(result)
+        else:
+            call = classify_by_metrics(pedigree)
+            values = network_metrics(pedigree)
+            rows.append({'family': name, 'call': call, **values})
+            text = (f'Family {name}, by the original PedNet metric classifier: {call}\n  ' +
+                    ', '.join(f'{k} {v:.3f}' for k, v in values.items()))
+        if not args.tsv:
+            print(text)
+            print()
+    if args.tsv:
+        _write_tsv(rows, sys.stdout)
+    return 0
+
+
+def _graph(args) -> int:
+    families = _families(args)
+    if (args.kinship or args.graphml) and len(families) > 1:
+        raise PedigreeError('--kinship and --graphml need --family, since the PED file has more than one family')
+    for name, pedigree in families.items():
+        graph = pedgraph.pedigree_graph(pedigree)
+        couples = {(p.father, p.mother) for p in pedigree.people if p.father is not None}
+        generations = pedigree.generations()
+        founders = [n for n in graph if graph.in_degree(n) == 0]
+        print(f'Family {name}: {_count(graph.number_of_nodes(), "person", "people")} in '
+              f'{_count(max(generations.values()) + 1, "generation")}, {len(pedigree.affected())} affected; '
+              f'{_count(len(founders), "founder")} and {_count(len(couples), "couple")} with children')
+        found = pedgraph.loops(pedigree)
+        if found:
+            for loop in found:
+                print(f'  a loop, from {loop.kind}: {", ".join(loop.people)}')
+        else:
+            print('  no loops')
+        inbred = {pid: f for pid, f in pedgraph.inbreeding(pedigree).items() if f > 0}
+        if inbred:
+            print('  inbred: ' + ', '.join(f'{pid} (F = {f:.4f})' for pid, f in inbred.items()))
+        print(f'  width {pedgraph.pedigree_width(pedigree)} (the most people no one of whom is another\'s ancestor)')
+        plan = pedgraph.elimination(pedigree)
+        print(f'  exact likelihoods: elimination width {plan.width}, so the moral graph\'s treewidth is at most '
+              f'{plan.width - 1}' + ('' if plan.exact else
+                                     f'; too many loops for exact likelihoods (a table of {plan.largest_table:,} '
+                                     'states)'))
+        affected = pedigree.affected()
+        pairs = [(a, b) for i, a in enumerate(affected) for b in affected[i + 1:]]
+        matrix = pedgraph.kinship_matrix(pedigree)
+        named = [(a, b, pedgraph.relationship(pedigree, a, b, matrix)) for a, b in pairs]
+        named = [x for x in named if x[2].degree is not None]
+        named.sort(key=lambda x: (-x[2].kinship, x[0], x[1]))
+        if named:
+            print('  affected relatives, the closest first:')
+            for a, b, r in named[:args.pairs]:
+                print(f'    {b} is the {r.name} of {a} ({_ordinal_degree(r.degree)} degree, kinship {r.kinship:.4f})')
+            if len(named) > args.pairs:
+                print(f'    ... and {len(named) - args.pairs} more pairs')
+        values = network_metrics(pedigree)
+        print('  network metrics (the original PedNet\'s):')
+        _print_values(values)
+        print('  pattern features:')
+        _print_values(pattern_features(pedigree))
+        central = sorted(pedgraph.centrality(pedigree).items(), key=lambda x: -x[1])[:3]
+        print('  most central (betweenness): ' + ', '.join(f'{pid} {v:.3f}' for pid, v in central))
+        if args.kinship:
+            ids, phi = pedgraph.kinship_matrix(pedigree, x_linked=args.x)
+            keep = [k for k, pid in enumerate(ids) if not pedigree[pid].placeholder]
+            with open(args.kinship, 'w', newline='') as handle:
+                writer = csv.writer(handle, delimiter='\t', lineterminator='\n')
+                writer.writerow([''] + [ids[k] for k in keep])
+                for k in keep:
+                    writer.writerow([ids[k]] + [f'{phi[k, j]:.6g}' for j in keep])
+            print(f'  wrote the {"X-linked " if args.x else ""}kinship coefficients to {args.kinship}')
+        if args.graphml:
+            pedgraph.write_graph(pedigree, args.graphml, mating=args.mating)
+            print(f'  wrote the {"mating" if args.mating else "pedigree"} graph to {args.graphml}')
+    return 0
+
+
+def _print_values(values, per_line=4):
+    items = [f'{k} {v:.3f}' for k, v in values.items()]
+    for start in range(0, len(items), per_line):
+        print('    ' + ', '.join(items[start:start + per_line]))
+
+
+def _ordinal_degree(degree: int) -> str:
+    return {1: 'first', 2: 'second', 3: 'third', 4: 'fourth', 5: 'fifth'}.get(degree, f'{degree}th')
+
+
+def _count(n: int, one: str, many: Optional[str] = None) -> str:
+    """'1 variant', '2 variants'"""
+    return f'{n} {one if n == 1 else (many or one + "s")}'
+
+
+def _format(value, digits=2):
+    if value is None:
+        return '-'
+    if isinstance(value, float):
+        return f'{value:.{digits}f}'
+    return str(value)
+
+
+def _print_table(header, table):
+    widths = [max(len(str(row[i])) for row in [header] + table) for i in range(len(header))]
+    for row in [header] + table:
+        print('  '.join(str(cell).ljust(w) for cell, w in zip(row, widths)).rstrip())
+
+
+def _note_strangers(names, people):
+    """Say which genotyped samples are in no family, and stop if none of them is in one"""
+    missing = sorted(set(names) - set(people))
+    if missing and len(missing) == len(set(names)):
+        raise PedigreeError('None of the genotyped samples is in the PED file: their names must be the IDs of the '
+                            f'PED file ({", ".join(missing[:3])}{"..." if len(missing) > 3 else ""})')
+    if missing:
+        print(f'note: {_count(len(missing), "genotyped sample")} {"is" if len(missing) == 1 else "are"} in no family '
+              f'of the PED file and {"is" if len(missing) == 1 else "are"} left out '
+              f'({", ".join(missing[:5])}{"..." if len(missing) > 5 else ""})', file=sys.stderr)
+
+
+def _read_variants(args, people):
+    path = str(args.variants).lower()
+    if path.endswith(('.vcf', '.vcf.gz', '.vcf.bgz')):
+        _note_strangers(vcf_samples(args.variants), people)
+        variants = read_vcf(args.variants, samples=people, frequency_key=args.frequency_key,
+                            passed_only=args.passed_only, gene_key=args.gene_key)
+    else:
+        variants = read_genotype_table(args.variants)
+        _note_strangers({pid for v in variants for pid in v.genotypes}, people)
+    if args.max_frequency is not None:
+        kept = [v for v in variants if v.allele_frequency is None or v.allele_frequency <= args.max_frequency]
+        if len(kept) < len(variants):
+            n = len(variants) - len(kept)
+            print(f'note: {_count(n, "variant")} with an allele frequency above {args.max_frequency} '
+                  f'{"is" if n == 1 else "are"} left out', file=sys.stderr)
+        variants = kept
+    return variants
+
+
+def _rank(args) -> int:
+    families = _families(args)
+    people = {pid for pedigree in families.values() for pid in pedigree.ids}
+    variants = _read_variants(args, people)
+    options = dict(modes=args.modes, penetrance=args.penetrance, phenocopy=args.phenocopy,
+                   min_frequency=args.min_frequency, error_rate=args.error_rate, compound=not args.no_compound)
+    if len(families) > 1:
+        return _rank_across(args, families, variants, options)
+    pedigree = next(iter(families.values()))
+    scores = rank_variants(pedigree, variants, proband=args.proband, **options)
+    if args.out:
+        with open(args.out, 'w', newline='') as handle:
+            _write_tsv([s.row() for s in scores], handle)
+    shown = scores[:args.top] if args.top else scores
+    pairs = sum(s.compound for s in scores)
+    print(f'Family {pedigree.family}: {_count(len(scores) - pairs, "variant")}'
+          + (f' and {_count(pairs, "pair")} of variants in one gene' if pairs else '') + ', the most likely cause first')
+    header = ['rank', 'candidate', 'log10 odds', 'log10 BF', 'evidence', 'best mode', 'affected carriers',
+              'unaffected carriers', 'note']
+    table = [[_format(s.rank, 1), s.id, _format(s.log10_odds), _format(s.log10_bf), s.evidence or '-',
+              (s.best_mode + ' (compound)' if s.compound and s.best_mode else s.best_mode) or '-',
+              f'{s.affected_carriers}/{s.affected_carriers + s.affected_noncarriers}',
+              f'{s.unaffected_carriers}/{s.unaffected_carriers + s.unaffected_noncarriers}', s.notes]
+             for s in shown]
+    _print_table(header, table)
+    if args.top and len(scores) > args.top:
+        print(f'... and {len(scores) - args.top} more' + (f' (all in {args.out})' if args.out else ''))
+    return 0
+
+
+def _rank_across(args, families, variants, options) -> int:
+    combined = rank_variants_across(families, variants, **options)
+    if args.out:
+        with open(args.out, 'w', newline='') as handle:
+            _write_tsv([c.row() for c in combined], handle)
+    print(f'Families {", ".join(families)}: {_count(len(combined), "candidate")} carried by an affected person in at '
+          'least one family, the most likely cause over the families first')
+    shown = combined[:args.top] if args.top else combined
+    header = ['rank', 'candidate', 'log10 odds', 'log10 BF', 'evidence', 'each family\'s own log10 BF']
+    table = [[_format(c.rank, 1), c.id, _format(c.log10_odds), _format(c.log10_bf), c.evidence or '-',
+              ', '.join(f'{name} {_format(s.log10_bf)}' for name, s in c.families.items())] for c in shown]
+    _print_table(header, table)
+    for c in shown:
+        if c.note:
+            print(f'note: {c.id}: {c.note}')
+        elif c.evidence_withheld:
+            print(f'note: no evidence is given for {c.id}: {c.evidence_withheld}')
+    if args.top and len(combined) > args.top:
+        print(f'... and {len(combined) - args.top} more' + (f' (all in {args.out})' if args.out else ''))
+    return 0
+
+
+def _check(args) -> int:
+    for name, pedigree in _families(args).items():
+        generations = pedigree.generations()
+        print(f'Family {name}: {len([p for p in pedigree.people if not p.placeholder])} people, '
+              f'{len(pedigree.affected())} affected, {max(generations.values()) + 1} generations')
+        related = pedigree.consanguineous()
+        if related:
+            print(f'  children of related parents: {", ".join(sorted(related))}')
+        for note in pedigree.notes + pedigree.problems():
+            print(f'  note: {note}')
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog='pednet', description='Pedigrees as graphs: the structure of a family, '
+                                     'the mode of inheritance of its condition, and the co-segregation of candidate '
+                                     'variants with it.')
+    parser.add_argument('--version', action='version', version=f'pednet {__version__}')
+    sub = parser.add_subparsers(dest='command', required=True)
+
+    graph = sub.add_parser('graph', help='the pedigree as a graph: its structure, loops, kinship and patterns')
+    graph.add_argument('ped', help='the PED file')
+    graph.add_argument('--family', help='only this family')
+    graph.add_argument('--pairs', type=int, default=10, help='how many pairs of affected relatives to list (default 10)')
+    graph.add_argument('--kinship', help='write the kinship coefficients of everyone to this file, separated by tabs')
+    graph.add_argument('--x', action='store_true', help='with --kinship, the coefficients for the X chromosome')
+    graph.add_argument('--graphml', help='write the graph as GraphML, for network tools such as Gephi or Cytoscape')
+    graph.add_argument('--mating', action='store_true',
+                       help='with --graphml, write the mating graph, with a node for each couple')
+    graph.set_defaults(run=_graph)
+
+    mode = sub.add_parser('mode', help='the probability of each mode of inheritance')
+    _common(mode)
+    mode.add_argument('--method', choices=('likelihood', 'patterns', 'metrics'), default='likelihood',
+                      help='likelihood: the exact likelihood of the phenotypes under each mode, summed over '
+                           'everyone\'s genotypes (the default); patterns: the classifier of the pattern of affected '
+                           'people in the graph; metrics: the original PedNet\'s network metric classifier, AD or AR')
+    mode.add_argument('--threshold', type=float, default=0.8,
+                      help='the probability needed to call a mode (default: 0.8)')
+    mode.add_argument('--together', action='store_true',
+                      help='take the families as having the same condition, and give one answer for them all')
+    mode.add_argument('--tsv', action='store_true', help='print a table separated by tabs')
+    mode.set_defaults(run=_mode)
+
+    rank = sub.add_parser('rank', help='candidate variants ranked by co-segregation with the condition',
+                          description='Ranks candidate variants by how well they co-segregate with the condition. '
+                          'With several families in the PED file (and no --family), the families are taken to have '
+                          'the same condition, with one mode of inheritance, and each candidate is ranked by its '
+                          'evidence over the families in which an affected person carries it: the sum of their log10 '
+                          'Bayes factors when the mode is given (--modes AD, say), and otherwise more than the sum if '
+                          'the families agree on the mode, and less if they point to different modes.')
+    _common(rank)
+    rank.add_argument('variants', help='a VCF file (.vcf or .vcf.gz), or a table with a column per person')
+    rank.add_argument('--frequency-key', default='AF', help='the INFO field with the allele frequency (default: AF)')
+    rank.add_argument('--gene-key', help='the INFO field naming the gene (default: the first of CSQ, ANN, BCSQ, GENE, '
+                                         'SYMBOL, Gene.refGene, Gene.ensGene and GENEINFO present)')
+    rank.add_argument('--passed-only', action='store_true', help='keep only VCF sites that passed their filters')
+    rank.add_argument('--max-frequency', type=float,
+                      help='leave out variants with an allele frequency above this (by default none are left out)')
+    rank.add_argument('--min-frequency', type=float, default=MIN_VARIANT_FREQUENCY,
+                      help=f'treat rarer variants as having this frequency (default: {MIN_VARIANT_FREQUENCY})')
+    rank.add_argument('--error-rate', type=float, default=DEFAULT_ERROR_RATE,
+                      help=f'the chance that a genotype call is one copy out (default: {DEFAULT_ERROR_RATE})')
+    rank.add_argument('--no-compound', action='store_true',
+                      help='don\'t score pairs of variants in one gene as compound heterozygotes')
+    rank.add_argument('--top', type=int, default=20, help='how many to show (default: 20; 0 for all)')
+    rank.add_argument('--out', help='write every candidate\'s scores to this file, separated by tabs')
+    rank.set_defaults(run=_rank)
+
+    check = sub.add_parser('check', help='what PedNet makes of a PED file')
+    check.add_argument('ped', help='the PED file')
+    check.add_argument('--family', help='only this family')
+    check.set_defaults(run=_check)
+
+    args = parser.parse_args(argv)
+    try:
+        status = args.run(args)
+        sys.stdout.flush()      # here rather than as Python exits, so that a reader who has stopped is noticed below
+        return status
+    except BrokenPipeError:
+        # whatever was reading the output (head, say) has stopped: stop quietly, sending what is left to nowhere so
+        # that Python doesn't complain again as it exits
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        return 1
+    except (PedigreeError, ValueError, OSError) as error:
+        print(f'pednet: {error}', file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

pednet/compound.py

@@ -0,0 +1,180 @@
+"""Pairs of variants in one gene, as a compound heterozygote.
+
+A recessive condition is often caused by two different variants in the same gene, one on each copy of the gene.
+Neither variant then segregates as a recessive variant should (the affected people have one copy of each, not two
+of either), so PedNet also scores the pairs of variants in a gene that an affected person carries both of.
+
+The gene is then a locus with four haplotypes: a copy of the gene with neither variant (r), with the first only
+(a), with the second only (b), or with both (c, the two variants in cis). Someone's genotype is a pair of
+haplotypes, which gives ten states; on the X chromosome a man has a single haplotype, four states. Under a
+recessive mode the disease genotype is two copies that each carry a variant (on the X, a man's one copy). In a
+founder the haplotypes have the frequencies they would have in linkage equilibrium. Two rare variants on one copy
+(cis) are then about as likely in a founder as one on each copy (trans), and the family's genotypes show which
+they are: in cis, the two are passed on together.
+"""
+from functools import lru_cache
+from typing import TYPE_CHECKING, Dict, Optional, Sequence, Tuple
+
+import numpy as np
+
+from .engine import Network
+from .inheritance import _logsumexp
+from .models import Model, call_codes, call_probability
+from .pedigree import Pedigree
+
+if TYPE_CHECKING:
+    from .segregation import Variant
+
+# the copies of the first and of the second variant on each haplotype: r, a, b and c
+HAPLOTYPES = ((0, 0), (1, 0), (0, 1), (1, 1))
+PAIRS = tuple((i, j) for i in range(4) for j in range(i, 4))
+PAIR_MODES = ('AR', 'XLR')
+
+
+@lru_cache(maxsize=None)
+def _states(kind: str) -> Tuple[Tuple[Tuple[int, ...], bool], ...]:
+    """Each state of a genotype of this kind, as its haplotypes and whether it is a man's"""
+    men = tuple(((h,), True) for h in range(4))
+    pairs = tuple((pair, False) for pair in PAIRS)
+    return {'A': pairs, 'F': pairs, 'M': men, 'U': men + pairs}[kind]
+
+
+class PairLocus:
+    """The four haplotypes of a pair of variants in one gene, as a locus for Network"""
+
+    @staticmethod
+    def domain(kind: str) -> int:
+        return len(_states(kind))
+
+    @staticmethod
+    def transmission(kind: str) -> np.ndarray:
+        return _transmission(kind)
+
+
+@lru_cache(maxsize=None)
+def _transmission(kind: str) -> np.ndarray:
+    """P(child's state | father's state, mother's state), indexed [child, father, mother], as in models.transmission"""
+    n = len(PAIRS)
+    position = {pair: k for k, pair in enumerate(PAIRS)}
+    if kind == 'A':
+        t = np.zeros((n, n, n))
+        for f, father in enumerate(PAIRS):
+            for m, mother in enumerate(PAIRS):
+                for a in father:
+                    for b in mother:
+                        t[position[tuple(sorted((a, b)))], f, m] += 0.25
+        return t
+    son = np.zeros((4, 4, n))
+    daughter = np.zeros((n, 4, n))
+    for h in range(4):
+        for m, mother in enumerate(PAIRS):
+            for b in mother:
+                # a son has one of his mother's copies; a daughter her father's only copy and one of her mother's
+                son[b, h, m] += 0.5
+                daughter[position[tuple(sorted((h, b)))], h, m] += 0.5
+    if kind == 'M':
+        return son
+    if kind == 'F':
+        return daughter
+    return np.concatenate([0.5 * son, 0.5 * daughter], axis=0)
+
+
+def founder_prior(kind: str, q1, q2) -> np.ndarray:
+    """The founder genotype probabilities, for variant frequencies q1 and q2 (single values, or one per batch)"""
+    q1, q2 = np.asarray(q1, dtype=float), np.asarray(q2, dtype=float)
+    hap = np.stack([(1 - q1) * (1 - q2), q1 * (1 - q2), (1 - q1) * q2, q1 * q2], axis=-1)
+    diploid = np.stack([hap[..., i] * hap[..., j] * (1.0 if i == j else 2.0) for i, j in PAIRS], axis=-1)
+    if kind in ('A', 'F'):
+        return diploid
+    if kind == 'M':
+        return hap
+    return np.concatenate([0.5 * hap, 0.5 * diploid], axis=-1)
+
+
+@lru_cache(maxsize=None)
+def genotype_table(kind: str, error_rate: float) -> np.ndarray:
+    """genotype_factor for every pair of calls, indexed by the codes of models.call_codes; read-only"""
+    calls = (None, 0, 1, 2)
+    table = np.stack([np.stack([genotype_factor(kind, a, b, error_rate) for b in calls]) for a in calls])
+    table.flags.writeable = False
+    return table
+
+
+def genotype_factor(kind: str, called1: Optional[int], called2: Optional[int], error_rate: float) -> np.ndarray:
+    """P(the two genotype calls) for each state, with the error model of models.genotype_factor for each call"""
+    out = np.ones(len(_states(kind)))
+    for k, (haps, male) in enumerate(_states(kind)):
+        if called1 is not None:
+            out[k] *= call_probability(sum(HAPLOTYPES[h][0] for h in haps), male, called1, error_rate)
+        if called2 is not None:
+            out[k] *= call_probability(sum(HAPLOTYPES[h][1] for h in haps), male, called2, error_rate)
+    return out
+
+
+def _damaged(haps) -> int:
+    """How many of the copies carry a variant"""
+    return sum(1 for h in haps if h != 0)
+
+
+def affected_probability(model: Model, kind: str) -> np.ndarray:
+    """P(affected) for each state, under a recessive mode (AR, or XLR with its carrier penetrance for women)"""
+    f, p = model.penetrance, model.phenocopy
+    h = p if model.carrier_penetrance is None else model.carrier_penetrance
+    out = []
+    for haps, male in _states(kind):
+        damaged = _damaged(haps)
+        if male:
+            out.append(f if damaged else p)
+        elif model.mode == 'XLR':
+            out.append(f if damaged == 2 else (h if damaged == 1 else p))
+        else:
+            out.append(f if damaged == 2 else p)
+    return np.array(out)
+
+
+def phenotype_factor(model: Model, kind: str, phenotype: int) -> np.ndarray:
+    affected = affected_probability(model, kind)
+    if phenotype == 2:
+        return affected
+    if phenotype == 1:
+        return 1 - affected
+    return np.ones(len(affected))
+
+
+def has_disease_genotype(copies1: int, copies2: int, male: Optional[bool]) -> bool:
+    """Whether genotype calls fit the disease genotype of a compound heterozygote (or a homozygote of either)"""
+    if male:
+        return copies1 >= 1 or copies2 >= 1
+    return (copies1 >= 1 and copies2 >= 1) or copies1 == 2 or copies2 == 2
+
+
+def pair_log_likelihoods(pedigree: Pedigree, net: Network, pairs: Sequence[Tuple['Variant', 'Variant']],
+                         frequencies: Sequence[Tuple[float, float]], modes: Sequence[str], models: Dict[str, Model],
+                         pens: Sequence[float], log_w: np.ndarray, error_rate: float) -> Dict[str, np.ndarray]:
+    """
+    For each mode, the natural log of P(phenotypes | both pairs' genotypes, the pair causes the condition) for each
+    pair, averaged over the penetrances with weights exp(log_w). net must be a Network with a PairLocus.
+    """
+    V, F = len(pairs), len(pens)
+    q1 = np.array([f[0] for f in frequencies])
+    q2 = np.array([f[1] for f in frequencies])
+    first, second = [a for a, _ in pairs], [b for _, b in pairs]
+    evidence = []
+    for i, (kind, person) in enumerate(zip(net.kinds, pedigree.people)):
+        e = genotype_table(kind, error_rate)[call_codes(first, person.id), call_codes(second, person.id)]
+        if net.parents[i] is None:
+            e = e * founder_prior(kind, q1, q2)
+        evidence.append(e)
+    log_genotypes = net.log_likelihood(evidence)
+    out = {}
+    for mode in modes:
+        model = models[mode]
+        unary = []
+        for i, (kind, person) in enumerate(zip(net.kinds, pedigree.people)):
+            phen = np.stack([phenotype_factor(model.with_(penetrance=f), kind, person.phenotype) for f in pens])
+            unary.append((phen[:, None, :] * evidence[i][None, :, :]).reshape(F * V, -1))
+        joint = net.log_likelihood(unary).reshape(F, V)
+        with np.errstate(invalid='ignore'):
+            # NaN where the genotypes have no probability at all, which the caller reports
+            out[mode] = _logsumexp(joint + log_w[:, None], axis=0) - log_genotypes
+    return out