triohap 0.4.0__py3-none-any.whl

triohap/__init__.py

@@ -0,0 +1,2 @@
+"""Research prototype: trio-aware regional haplotype matching."""
+__version__ = "0.4.0"

triohap/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

triohap/catalogue.py

@@ -0,0 +1,297 @@
+"""Import an existing regional pangenome analysis without changing its files.
+
+Full site-defined haplotypes and assembly membership are retained in JSON.
+Only literal SNP records are exposed to the current SNP matching engine.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+
+from .vcf import parse_region
+
+SCHEMA = 'triohap.catalogue.v1'
+BASES = frozenset('ACGT')
+
+
+def _table(path):
+    with Path(path).open(newline='') as handle:
+        reader = csv.DictReader(handle, delimiter='\t')
+        fields = reader.fieldnames or []
+        if not fields or len(fields) != len(set(fields)):
+            raise ValueError(f'{path}: missing or duplicate TSV column names')
+        rows = list(reader)
+    if any(None in row or any(value is None for value in row.values()) for row in rows):
+        raise ValueError(f'{path}: wrong number of TSV columns')
+    return fields, rows
+
+
+def _require(fields, required, filename):
+    missing = set(required) - set(fields)
+    if missing:
+        raise ValueError(f'{filename}: missing columns {sorted(missing)}')
+
+
+def _index(token, site, where):
+    if token == '.':
+        return None
+    try:
+        index = int(token)
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f'{where}: invalid allele index {token!r}') from exc
+    if index < 0 or index > len(site['alts']):
+        raise ValueError(f'{where}: allele index {index} outside REF/ALT dictionary')
+    return index
+
+
+def _literal_snp(site):
+    return site['ref'] in BASES and all(a in BASES for a in site['alts'])
+
+
+def _digest(value):
+    return hashlib.sha256(json.dumps(value, separators=(',', ':'), sort_keys=True).encode()).hexdigest()
+
+
+def _audit(sites, haplotypes, unassigned):
+    snps = [i for i, site in enumerate(sites) if _literal_snp(site)]
+    projected = defaultdict(list)
+    for hap in haplotypes:
+        projected[tuple(hap['alleles'][i] for i in snps)].append(hap['id'])
+    groups = sorted((sorted(members) for members in projected.values()), key=lambda x: x[0])
+    return {
+        'variant_sites': len(sites),
+        'snp_sites': len(snps),
+        'non_snp_sites': len(sites) - len(snps),
+        'full_haplotype_classes': len(haplotypes),
+        'assembly_haplotypes': sum(h['count'] for h in haplotypes),
+        'unassigned_assembly_haplotypes': len(unassigned),
+        'unassigned_members': unassigned,
+        'snp_signature_classes': len(projected),
+        'snp_equivalence_groups': groups,
+        'snp_ambiguous_groups': [g for g in groups if len(g) > 1],
+        'snp_sites_missing_in_any_class': sum(any(h['alleles'][i] is None for h in haplotypes) for i in snps),
+        'note': 'SNP signatures describe the complete panel SNP projection, before patient missingness. '
+                'Full classes can remain indistinguishable even with every panel SNP observed. '
+                'Counts are assembly membership, not calibrated population priors.',
+    }
+
+
+def import_catalogue(bundle_dir, tag='core', build='GRCh38'):
+    """Validate pipeline TSVs and preserve full haplotype identities.
+
+    The matrix is authoritative for multi-digit allele indices. A compact
+    display-only ``allele_string`` is never parsed.
+    """
+    bundle = Path(bundle_dir)
+    if not tag or any(c in tag for c in '/\\') or tag in ('.', '..'):
+        raise ValueError('tag must be a simple filename suffix')
+    table_dir = bundle / 'results' / 'tables'
+    filenames = {
+        'sites': f'variant_sites.{tag}.tsv',
+        'matrix': f'haplotype_matrix.{tag}.tsv',
+        'assignments': f'haplotype_assignments.{tag}.tsv',
+        'classes': f'haplotypes.{tag}.tsv',
+    }
+    loaded = {key: _table(table_dir / name) for key, name in filenames.items()}
+    fields, raw_sites = loaded['sites']
+    _require(fields, ['chrom', 'pos', 'ref', 'alt'], filenames['sites'])
+    if not raw_sites:
+        raise ValueError('The source panel has no variant sites')
+    sites, positions = [], set()
+    for row in raw_sites:
+        chrom, pos, ref = row['chrom'], int(row['pos']), row['ref'].upper()
+        if not chrom or pos < 1 or not ref or ref == '.':
+            raise ValueError('Invalid site CHROM/POS/REF')
+        if (chrom, pos) in positions:
+            raise ValueError(f'Duplicate site coordinate {chrom}:{pos}; reconcile records before import')
+        positions.add((chrom, pos))
+        alts = [] if row['alt'] == '.' else row['alt'].upper().split(',')
+        if any(not a for a in alts) or len(set([ref] + alts)) != len(alts) + 1:
+            raise ValueError(f'Invalid or duplicate allele dictionary at {chrom}:{pos}')
+        site = {'chrom': chrom, 'pos': pos, 'ref': ref, 'alts': alts,
+                'kind': row.get('class', 'unspecified')}
+        site['is_literal_snp'] = _literal_snp(site)
+        sites.append(site)
+    if len({s['chrom'] for s in sites}) != 1:
+        raise ValueError('One catalogue must cover a single chromosome region')
+
+    matrix_header, matrix_rows = loaded['matrix']
+    expected_header = ['haplotype_id'] + [f"{s['chrom']}:{s['pos']}" for s in sites]
+    if matrix_header != expected_header:
+        raise ValueError('Haplotype matrix column order does not match variant_sites exactly')
+    matrix = {}
+    for row in matrix_rows:
+        name = row['haplotype_id']
+        if not name or name in matrix:
+            raise ValueError(f'Duplicate or empty matrix haplotype ID {name!r}')
+        matrix[name] = [_index(row[column], site, name + ':' + column)
+                        for column, site in zip(matrix_header[1:], sites)]
+
+    fields, assignment_rows = loaded['assignments']
+    _require(fields, ['haplotype_id', 'haplotype_class'], filenames['assignments'])
+    assignments = {}
+    for row in assignment_rows:
+        member = row['haplotype_id']
+        if member in assignments:
+            raise ValueError(f'Duplicate assignment for {member}')
+        assignments[member] = row['haplotype_class']
+    if set(assignments) != set(matrix):
+        raise ValueError('Assignments must cover every matrix haplotype exactly once; '
+                         f'missing={sorted(set(matrix)-set(assignments))[:5]}, '
+                         f'extra={sorted(set(assignments)-set(matrix))[:5]}')
+
+    fields, class_rows = loaded['classes']
+    _require(fields, ['haplotype_class', 'count'], filenames['classes'])
+    class_ids = [r['haplotype_class'] for r in class_rows]
+    if any(not c or c in ('.', 'NA') for c in class_ids) or len(class_ids) != len(set(class_ids)):
+        raise ValueError('Class IDs must be nonempty and unique')
+    members_by_class = defaultdict(list)
+    unassigned = []
+    for member, cls in assignments.items():
+        if cls in ('', '.', 'NA'):
+            unassigned.append(member)
+        elif cls not in class_ids:
+            raise ValueError(f'Assignment references unknown class {cls!r}')
+        else:
+            members_by_class[cls].append(member)
+
+    haplotypes, seen_signatures = [], {}
+    for row in class_rows:
+        cls = row['haplotype_class']
+        members = sorted(members_by_class[cls])
+        count = int(row['count'])
+        if not members or count != len(members):
+            raise ValueError(f'{cls}: catalogue count {count} disagrees with {len(members)} assigned members')
+        indices = matrix[members[0]]
+        if any(matrix[m] != indices for m in members[1:]):
+            raise ValueError(f'{cls}: members do not share one full-site allele vector')
+        signature = tuple(indices)
+        if signature in seen_signatures:
+            raise ValueError(f'{cls} and {seen_signatures[signature]} duplicate a full-site class')
+        seen_signatures[signature] = cls
+        alleles = [None if index is None else ([site['ref']] + site['alts'])[index]
+                   for index, site in zip(indices, sites)]
+        haplotypes.append({'id': cls, 'allele_indices': indices, 'alleles': alleles,
+                           'members': members, 'count': count,
+                           'signature_hash': _digest({'sites': sites, 'alleles': alleles})})
+    if not haplotypes:
+        raise ValueError('The source panel has no assigned haplotype classes')
+
+    summary_path = table_dir / f'summary.{tag}.json'
+    source_summary = {}
+    if summary_path.exists():
+        source_summary = json.loads(summary_path.read_text())
+        if source_summary.get('region'):
+            chrom, start, end = parse_region(source_summary['region'])
+            region_source = str(summary_path.relative_to(bundle))
+        else:
+            raise ValueError('Source summary is present but has no region')
+    else:
+        chrom = sites[0]['chrom']
+        start = min(s['pos'] for s in sites)
+        end = max(s['pos'] + len(s['ref']) - 1 for s in sites)
+        region_source = 'inferred_from_variant_extent; not the original window boundary'
+    if any(s['chrom'] != chrom or not (start <= s['pos'] <= end) for s in sites):
+        raise ValueError('Variant sites fall outside the declared catalogue region')
+    region = {'chrom': chrom, 'start': start, 'end': end,
+              'coordinate_system': '1-based-inclusive', 'source': region_source}
+    source_files = [table_dir / f for f in filenames.values()]
+    if summary_path.exists():
+        source_files.append(summary_path)
+    source = {'bundle_name': bundle.name, 'tag': tag,
+              'files': {str(p.relative_to(bundle)): {'sha256': hashlib.sha256(p.read_bytes()).hexdigest(),
+                                                    'size_bytes': p.stat().st_size}
+                        for p in source_files},
+              'build_note': 'Build supplied by caller; retained source coordinates are not lifted over.'}
+    if source_summary.get('vcf'):
+        source['upstream_vcf'] = source_summary['vcf']
+    return {'schema': SCHEMA, 'build': build, 'region': region, 'sites': sites,
+            'haplotypes': haplotypes, 'source': source,
+            'audit': _audit(sites, haplotypes, sorted(unassigned))}
+
+
+def _validate(catalogue):
+    if catalogue.get('schema') != SCHEMA:
+        raise ValueError(f'Expected catalogue schema {SCHEMA}')
+    sites, haps = catalogue.get('sites', []), catalogue.get('haplotypes', [])
+    if not sites or not haps or len({h['id'] for h in haps}) != len(haps):
+        raise ValueError('Catalogue requires sites and unique haplotype IDs')
+    positions = [(s['chrom'], s['pos']) for s in sites]
+    if len(set(positions)) != len(positions):
+        raise ValueError('Catalogue has duplicate site coordinates')
+    for hap in haps:
+        if len(hap['alleles']) != len(sites) or len(hap['allele_indices']) != len(sites):
+            raise ValueError('Catalogue allele vectors have wrong dimensions')
+        for site, index, allele in zip(sites, hap['allele_indices'], hap['alleles']):
+            if index is None:
+                if allele is not None:
+                    raise ValueError('Missing allele index must retain a missing allele')
+            elif (not isinstance(index, int) or isinstance(index, bool) or index < 0 or
+                  index > len(site['alts']) or ([site['ref']] + site['alts'])[index] != allele):
+                raise ValueError('Catalogue allele index and sequence disagree')
+
+
+def read_catalogue(path, region=None):
+    """Expose a saved catalogue's literal SNP projection to the matcher."""
+    catalogue = json.loads(Path(path).read_text())
+    _validate(catalogue)
+    requested = parse_region(region)
+    records, diagnostics = {}, []
+    for index, site in enumerate(catalogue['sites']):
+        chrom, pos, ref = site['chrom'], site['pos'], site['ref']
+        if requested and (chrom != requested[0] or not requested[1] <= pos <= requested[2]):
+            continue
+        if not _literal_snp(site):
+            diagnostics.append({'reason': 'catalogue_non_snp_not_scored', 'chrom': chrom, 'pos': pos,
+                                'ref': ref, 'alts': site['alts'],
+                                'detail': 'Full allele retained in catalogue; SNP matcher does not score this record.'})
+            continue
+        records[(chrom, pos, ref)] = {'chrom': chrom, 'pos': pos, 'ref': ref,
+            'alleles': {h['id']: h['alleles'][index] for h in catalogue['haplotypes']}}
+    return {'haplotypes': [h['id'] for h in catalogue['haplotypes']], 'records': records,
+            'diagnostics': diagnostics, 'source': str(path), 'references': [catalogue['build']],
+            'contig_lengths': {}, 'catalogue': catalogue}
+
+
+def write_catalogue(catalogue, outdir):
+    """Write the catalogue, its explicit SNP table, and audit metadata."""
+    _validate(catalogue)
+    outdir = Path(outdir)
+    if outdir.exists() and any(outdir.iterdir()):
+        raise ValueError('Output directory must be new or empty')
+    outdir.mkdir(parents=True, exist_ok=True)
+    (outdir / 'catalogue.json').write_text(json.dumps(catalogue, indent=2) + '\n')
+    (outdir / 'audit.json').write_text(json.dumps(catalogue['audit'], indent=2) + '\n')
+    with (outdir / 'panel.snps.tsv').open('w', newline='') as handle:
+        writer = csv.writer(handle, delimiter='\t')
+        writer.writerow(['CHROM', 'POS', 'REF'] + [h['id'] for h in catalogue['haplotypes']])
+        for i, site in enumerate(catalogue['sites']):
+            if _literal_snp(site):
+                writer.writerow([site['chrom'], site['pos'], site['ref']] +
+                                [h['alleles'][i] if h['alleles'][i] is not None else '.'
+                                 for h in catalogue['haplotypes']])
+    return outdir
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Import a regional pangenome analysis catalogue')
+    parser.add_argument('--bundle', required=True)
+    parser.add_argument('--tag', default='core')
+    parser.add_argument('--build', default='GRCh38')
+    parser.add_argument('--out', required=True)
+    args = parser.parse_args(argv)
+    try:
+        catalogue = import_catalogue(args.bundle, tag=args.tag, build=args.build)
+        write_catalogue(catalogue, args.out)
+    except (ValueError, OSError, KeyError) as exc:
+        parser.exit(2, f'triohap catalogue: {exc}\n')
+    print(json.dumps({'catalogue': str(Path(args.out) / 'catalogue.json'), 'audit': catalogue['audit']}, indent=2))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

triohap/catalogue_plot.py

@@ -0,0 +1,248 @@
+"""Draw the full regional catalogue without discarding unobserved variation.
+
+The fixed panel layout is independent of the proband's markers or assignments.
+Edges count unequal variant records, not differing bases. Patient overlays
+preserve shared support for sets of catalogue haplotypes; they do not split
+an observed-marker class's weight among indistinguishable full haplotypes.
+"""
+from __future__ import annotations
+
+import argparse
+from collections import defaultdict
+import json
+from pathlib import Path
+import textwrap
+
+
+def _catalogue_tree(haplotypes):
+    """Deterministic Prim MST, with stable ties resolved by catalogue order."""
+    n = len(haplotypes)
+    if n < 2:
+        return []
+    vectors = [h['allele_indices'] for h in haplotypes]
+    if len({len(v) for v in vectors}) != 1:
+        raise ValueError('Catalogue haplotypes have different marker counts')
+    if any(a is None for v in vectors for a in v):
+        raise ValueError('Full-catalogue graph requires complete variant vectors; missing is not reference')
+    distance = lambda i, j: sum(a != b for a, b in zip(vectors[i], vectors[j]))
+    remaining = {j: (distance(0, j), 0) for j in range(1, n)}
+    edges = []
+    while remaining:
+        j = min(remaining, key=lambda k: (remaining[k][0], remaining[k][1], k))
+        weight, i = remaining.pop(j)
+        edges.append((i, j, weight))
+        for k in remaining:
+            candidate = distance(j, k), j
+            if candidate < remaining[k]:
+                remaining[k] = candidate
+    return edges
+
+
+def _layout(n, edges):
+    """Deterministic force layout; coordinates are schematic, not distances."""
+    import numpy as np
+    if n == 1:
+        return np.zeros((1, 2))
+    theta = np.linspace(0, 2 * np.pi, n, endpoint=False)
+    xy = np.column_stack((np.cos(theta), np.sin(theta)))
+    xy += np.random.default_rng(4927).normal(0, .035, (n, 2))
+    ideal = .5 / max(n, 1) ** .22
+    for step in range(1200):
+        delta = xy[:, None, :] - xy[None, :, :]
+        distances = np.maximum(np.linalg.norm(delta, axis=2), .025)
+        np.fill_diagonal(distances, 1e9)
+        force = (delta * (ideal ** 2 / distances ** 2)[:, :, None]).sum(axis=1)
+        for i, j, weight in edges:
+            diff = xy[j] - xy[i]
+            d = max(float(np.linalg.norm(diff)), .001)
+            pull = diff * d / (ideal * max(weight, 1) ** .4)
+            force[i] += pull
+            force[j] -= pull
+        force -= xy * .06
+        lengths = np.maximum(np.linalg.norm(force, axis=1), .001)
+        temperature = .045 * (1 - step / 1200) + .0005
+        xy += force / lengths[:, None] * np.minimum(lengths, temperature)[:, None]
+        xy -= xy.mean(axis=0)
+    # Principal-axis orientation is deterministic and keeps tall branches legible.
+    _, _, axes = np.linalg.svd(xy, full_matrices=False)
+    xy = xy @ axes.T
+    if xy[0, 0] < 0:
+        xy[:, 0] *= -1
+    if xy[0, 1] < 0:
+        xy[:, 1] *= -1
+    xy /= max(float(np.abs(xy).max()), .1)
+    return xy
+
+
+def _snp_equivalence(haplotypes, sites):
+    indices = [i for i, s in enumerate(sites) if s['is_literal_snp']]
+    groups = defaultdict(list)
+    for hap in haplotypes:
+        groups[tuple(hap['allele_indices'][i] for i in indices)].append(hap['id'])
+    return sorted((ids for ids in groups.values() if len(ids) > 1), key=lambda ids: (-len(ids), ids))
+
+
+def _placement_sets(result, catalogue_ids, side):
+    classes = {c['id']: c for c in result['classes']}
+    output = []
+    for item in result[side + '_marginals']:
+        members = classes[item['class_id']]['members']
+        unknown = set(members) - catalogue_ids
+        if unknown:
+            raise ValueError('Patient result members are not catalogue haplotype IDs: ' + ', '.join(sorted(unknown)))
+        output.append({'ids': sorted(members), 'weight': item['relative_weight']})
+    return output
+
+
+def draw_catalogue(catalogue, outdir, result=None, title=None):
+    """Write catalogue_graph.png/svg and return their absolute file paths.
+
+    With no result, display SNP-equivalence sets only, explicitly identifying
+    this as a panel audit. With a result, highlight leading shared maternal and
+    paternal assignments on exactly the same full-catalogue layout.
+    """
+    import numpy as np
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+
+    haps = catalogue['haplotypes']
+    sites = catalogue['sites']
+    if not haps or not sites:
+        raise ValueError('Catalogue graph needs haplotypes and variant sites')
+    if len(haps) > 250:
+        raise ValueError('Static catalogue plot is limited to 250 full haplotypes; retain all in JSON')
+    if any(len(h['allele_indices']) != len(sites) for h in haps):
+        raise ValueError('Catalogue allele vectors do not match site count')
+    ids = [h['id'] for h in haps]
+    if len(ids) != len(set(ids)):
+        raise ValueError('Duplicate catalogue haplotype IDs')
+    edges = _catalogue_tree(haps)
+    coordinates = _layout(len(haps), edges)
+    equivalents = _snp_equivalence(haps, sites)
+    snp_count = sum(s['is_literal_snp'] for s in sites)
+    snp_classes = len(haps) - sum(len(group) - 1 for group in equivalents)
+    region = catalogue['region']
+    region_text = f"{catalogue['build']} {region['chrom']}:{region['start']:,}–{region['end']:,}"
+
+    background, ink, quiet = '#f8fafc', '#24374c', '#576c81'
+    colors = ['#b33d72', '#296eaf', '#c77b18', '#459a83', '#785da8', '#af554d']
+    mat_color, pat_color = '#b83d72', '#267ba9'
+    group_color = {hid: colors[i % len(colors)] for i, group in enumerate(equivalents) for hid in group}
+    mat_sets = _placement_sets(result, set(ids), 'maternal') if result else []
+    pat_sets = _placement_sets(result, set(ids), 'paternal') if result else []
+    # Preserve ambiguity at the level inferred: every candidate in a set gets
+    # the same ring; no per-full-haplotype probability is manufactured.
+    def chosen(sets):
+        if not sets:
+            return []
+        cutoff = max(.02, sets[0]['weight'] * .1)
+        return [item for item in sets if item['weight'] >= cutoff]
+    chosen_mat, chosen_pat = chosen(mat_sets), chosen(pat_sets)
+    maternal_ids = {h for item in chosen_mat for h in item['ids']}
+    paternal_ids = {h for item in chosen_pat for h in item['ids']}
+
+    plt.rcParams.update({'font.family': 'DejaVu Sans', 'svg.fonttype': 'none'})
+    fig = plt.figure(figsize=(16, 10.5), facecolor=background)
+    heading = title or ('Regional haplotype catalogue: trio placement' if result else
+                        'Regional haplotype catalogue: SNP ambiguity')
+    fig.text(.04, .947, heading, size=22, weight='bold', color=ink)
+    fig.text(.04, .909, f"{region_text}  ·  {len(haps)} full haplotype classes  ·  "
+             f"{len(sites)} variant records  ·  {snp_count} literal SNP records", color=quiet, size=12)
+    fig.text(.04, .876, 'Trio placements shown on the unchanged full catalogue.' if result else
+             'Panel audit only — no trio or proband evidence supplied.',
+             color=mat_color if result else quiet, size=11, weight='bold')
+
+    ax = fig.add_axes([.035, .115, .665, .725])
+    ax.set_aspect('equal')
+    ax.set_xlim(-1.14, 1.14)
+    ymin, ymax = coordinates[:, 1].min(), coordinates[:, 1].max()
+    ax.set_ylim(min(-.75, ymin - .12), max(.75, ymax + .12))
+    ax.axis('off')
+    for i, j, d in edges:
+        a, b = coordinates[i], coordinates[j]
+        ax.plot([a[0], b[0]], [a[1], b[1]], color='#b8c6d3', lw=1.4, zorder=1)
+        if d != 1:
+            mid = (a + b) / 2
+            ax.text(*mid, str(d), ha='center', va='center', size=7.5, color=quiet,
+                    bbox={'facecolor': background, 'edgecolor': 'none', 'pad': .7}, zorder=3)
+    max_count = max(max(int(h.get('count', len(h.get('members', [])))), 1) for h in haps)
+    sizes = []
+    for hap in haps:
+        count = max(int(hap.get('count', len(hap.get('members', [])))), 1)
+        sizes.append(350 + 1200 * count / max_count)
+    for i, hap in enumerate(haps):
+        x, y = coordinates[i]
+        color = group_color.get(hap['id'], '#778ba0') if result is None else '#778ba0'
+        ax.scatter([x], [y], s=sizes[i], facecolor='white', edgecolor=color, lw=2, zorder=4)
+        ax.text(x, y, hap['id'], ha='center', va='center', size=8, color=color, weight='bold', zorder=6)
+        if hap['id'] in maternal_ids:
+            ax.scatter([x], [y], s=sizes[i] + 220, facecolor='none', edgecolor=mat_color, lw=2.2, zorder=5)
+        if hap['id'] in paternal_ids:
+            ax.scatter([x], [y], s=sizes[i] + 450, facecolor='none', edgecolor=pat_color, lw=2.2, zorder=5)
+
+    side = fig.add_axes([.735, .15, .235, .69])
+    side.axis('off')
+    y = .98
+    if result is None:
+        side.text(0, y, 'What SNPs can distinguish', size=15, color=ink, weight='bold')
+        y -= .085
+        side.text(0, y, f"{len(haps)} full classes → {snp_classes} SNP signatures", size=12, color=ink)
+        y -= .08
+        side.text(0, y, 'Each colored set is identical across all\nlisted literal SNPs. Non-SNP records\ndistinguish its full haplotypes.',
+                  size=10, color=quiet, va='top', linespacing=1.55)
+        y -= .17
+        for index, group in enumerate(equivalents[:6]):
+            label = textwrap.fill(', '.join(group), width=34)
+            side.text(0, y, label, color=colors[index % len(colors)], size=11,
+                      weight='bold', va='top', linespacing=1.4)
+            y -= .055 * (label.count('\n') + 1) + .055
+        if len(equivalents) > 6:
+            side.text(0, y, f'+ {len(equivalents) - 6} further sets in catalogue JSON', size=9, color=quiet)
+            y -= .06
+        side.text(0, y, 'Fewer callable patient SNPs can create\nfurther ties. The graph retains every\nfull haplotype and its original label.',
+                  size=10, color=quiet, va='top', linespacing=1.55)
+    else:
+        for label, sets, color in [('Maternal candidate sets', mat_sets, mat_color),
+                                    ('Paternal candidate sets', pat_sets, pat_color)]:
+            side.text(0, y, label, size=14, color=color, weight='bold')
+            y -= .065
+            for item in sets[:3]:
+                name = textwrap.fill(', '.join(item['ids']), width=29)
+                side.text(0, y, name, color=ink, size=10, va='top', linespacing=1.3)
+                side.text(1, y, f"{item['weight']:.1%}", color=color, size=10,
+                          ha='right', va='top', weight='bold')
+                y -= .038 * (name.count('\n') + 1) + .045
+            y -= .065
+        side.text(0, y, 'Support belongs to each entire set.\nRings do not assign that weight to\neach individual full haplotype.\n\nWeights are conditional ranking scores,\nnot calibrated clinical probabilities.',
+                  size=9.5, color=quiet, va='top', linespacing=1.5)
+
+    fig.text(.04, .082, 'Edges: minimum spanning tree over all variant records; labels count differing records (unlabelled edges = 1).',
+             size=10, color=quiet)
+    fig.text(.04, .055, 'Node size increases with supplied assembly count, including reference entries. Counts are not patient assignment priors.',
+             size=10, color=quiet)
+    fig.text(.04, .028, 'Schematic similarity network, not a genealogy or sequence pangenome graph. Layout is independent of patient evidence.',
+             size=10, color=quiet)
+    output = Path(outdir)
+    output.mkdir(parents=True, exist_ok=True)
+    png, svg = output / 'catalogue_graph.png', output / 'catalogue_graph.svg'
+    fig.savefig(png, dpi=160, facecolor=background)
+    fig.savefig(svg, facecolor=background)
+    plt.close(fig)
+    return {'png': str(png.resolve()), 'svg': str(svg.resolve())}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Plot a full haplotype catalogue and optional trio placement')
+    parser.add_argument('--catalogue', required=True)
+    parser.add_argument('--out', required=True)
+    parser.add_argument('--result')
+    parser.add_argument('--title')
+    args = parser.parse_args(argv)
+    catalogue = json.loads(Path(args.catalogue).read_text())
+    result = json.loads(Path(args.result).read_text()) if args.result else None
+    print(json.dumps(draw_catalogue(catalogue, args.out, result, args.title), indent=2))
+
+
+if __name__ == '__main__':
+    main()

triohap/cli.py

@@ -0,0 +1,73 @@
+"""Command-line entry point for an inspectable research prototype."""
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from . import __version__
+from .vcf import read_trio_vcf, read_trio_vcfs, read_panel
+from .core import match_haplotypes
+from .origin import read_unfazed_annotations
+from .report import write_report
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Research: match a trio to regional panel SNP haplotypes.')
+    parser.add_argument('--version', action='version', version=f'triohap {__version__}')
+    parser.add_argument('--trio', help='Joint VCF/gVCF containing all three trio members; detected automatically')
+    for role in ('child', 'mother', 'father'):
+        parser.add_argument('--' + role + '-vcf', help=f'Individual VCF/gVCF containing the {role}; detected automatically; supply all three')
+    parser.add_argument('--panel', required=True)
+    for role in ('child', 'mother', 'father'):
+        parser.add_argument('--' + role, required=True)
+    parser.add_argument('--region', required=True, help='CHROM:START-END; 1-based inclusive')
+    parser.add_argument('--build', required=True, help='Asserted shared coordinate reference (provenance only)')
+    parser.add_argument('--out', required=True)
+    parser.add_argument('--panel-format', choices=['auto', 'vcf', 'tsv', 'catalogue'], default='auto')
+    parser.add_argument('--epsilon', type=float, default=.01, help='Per-allele mismatch tolerance, not a calibrated error estimate')
+    parser.add_argument('--min-gq', type=float, default=0)
+    parser.add_argument('--top-n', type=int, default=20)
+    parser.add_argument('--max-classes', type=int, default=200)
+    parser.add_argument('--ignore-phase', action='store_true')
+    parser.add_argument('--unfazed-vcf', help='Optional parent-of-origin annotation; does not alter scores')
+    parser.add_argument('--no-plot', action='store_true')
+    parser.add_argument('--title', default='Trio-aware regional haplotype matches')
+    args = parser.parse_args(argv)
+    individual_paths = (args.child_vcf, args.mother_vcf, args.father_vcf)
+    if args.trio and any(individual_paths):
+        parser.error('Use --trio OR all three --child-vcf, --mother-vcf and --father-vcf inputs.')
+    if not args.trio and not all(individual_paths):
+        parser.error('Supply --trio OR all three --child-vcf, --mother-vcf and --father-vcf inputs.')
+    try:
+        output = Path(args.out)
+        if output.exists() and any(output.iterdir()):
+            raise ValueError(f'Output directory {output} is not empty. Choose a new directory to preserve previous results.')
+        panel = read_panel(args.panel, region=args.region, format=args.panel_format)
+        trio_options = dict(child=args.child, mother=args.mother, father=args.father,
+                            region=args.region, min_gq=args.min_gq, reference_sites=panel['records'])
+        if args.trio:
+            trio = read_trio_vcf(args.trio, **trio_options)
+        else:
+            trio = read_trio_vcfs(*individual_paths, **trio_options)
+        result = match_haplotypes(trio, panel, epsilon=args.epsilon, ignore_phase=args.ignore_phase,
+                                 max_classes=args.max_classes, top_n=args.top_n)
+        if 'catalogue' in panel:
+            result['catalogue'] = panel['catalogue']
+        result['provenance'] = {'program': 'triohap', 'version': __version__,
+                                'generated_utc': datetime.now(timezone.utc).isoformat(),
+                                'region': args.region, 'asserted_coordinate_build': args.build,
+                                'build_note': 'Caller assertion; no reference FASTA validation or liftover performed.'}
+        if args.unfazed_vcf:
+            result['unfazed_annotations'] = read_unfazed_annotations(
+                args.unfazed_vcf, args.child, args.region, trio=trio, asserted_build=args.build)
+            result['sources']['unfazed_annotation'] = args.unfazed_vcf
+        write_report(result, output, args.title, plot=not args.no_plot)
+        print(json.dumps({'report': str(output / 'report.html'), 'summary': result['summary']}, indent=2))
+        return 0
+    except (ValueError, OSError, ImportError) as exc:
+        print(f'triohap: {exc}', file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())