#!/usr/bin/env python3 """render_report.py: the text and HTML reports, both from one summary. render_report.py --sample S --sample-dir DIR [--json OUT.json] [-o REPORT.txt] [-o REPORT.html] render_report.py --summary IN.json [-o REPORT.txt] [-o REPORT.html] ... [--search-index INDEX.json] -o writes the text report for a .txt name and the HTML report for .html. --search-index also writes every gene and rsID the results mention, with the sections that name them (bin/results_index.py); the HTML report closes with the same list. With --sample-dir it first collects the summary (bin/collect_summary.py) and writes it to --json (default DIR/summary.json). Every number in both reports comes from that summary, so the two cannot disagree. A section whose result is from an earlier run (state "stale") is shown with that date and a STALE mark, and one whose step failed in the latest run (state "failed") says Failed. Standard library only. """ import argparse import html import json import os import re import sys sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) import collect_summary # noqa: E402 import results_index # noqa: E402 import report_charts # noqa: E402 E = html.escape def stale_note(sec): if sec["state"] == "stale": return f"STALE: {sec['note']}" if sec["state"] == "unreadable": return f"could not be read: {sec['note']}" if sec["state"] == "failed": return f"FAILED: {sec['note']}" return "" # Sentences both reports print, kept to what the pipeline can back. CLINVAR_FREQ_NOTE = ("Check every P/LP hit's population frequency, a heterozygous hit in a dominant gene as well as " "a homozygous one: a hit above 1% in gnomAD is unlikely to be a high-penetrance finding, and a " "hit whose frequency is unknown has not been checked.") CALLABILITY_NOTE = ("A gene listed as not read could not be read reliably: too few of its reads were placed on it " "with confidence, so a 'no finding' in it says nothing. A gene with a caller of its own is " "left to that caller's section.") HLA_NOTE = ("HLA typing from short-read WGS is approximate. If either HLA-A or HLA-B allele has a T1K quality " "of 0 or less, that gene is not passed to PharmCAT (step 36).") EH_NOTE = ("Repeat-expansion calls from short reads can be wrong at some loci, and a long expansion " "cannot be sized. Disease thresholds: docs/interpreting-results.md.") TELOMERE_UNIT = "intratelomeric reads per million reads with 48-52% GC" TELOMERE_NOTE = (f"Relative telomere content ({TELOMERE_UNIT}), not a telomere length: compare it only with " "samples of a similar age sequenced on the same platform (docs/10-telomere-analysis.md).") ANCESTRY_FINE_NOTE = ("Each name is a group of reference populations we put together and named, not a nationality. " "Continental groups are well apart; neighbouring regions are not: splits within Iberia are weak " "for every method, and Greek and Southern Italian ancestry overlap. Read a regional fraction " "with its bootstrap range. See docs/26b-ancestry-fine.md.") ANCESTRY_FINE_LEVELS = (("continent", "Continental groups"), ("region", "Regional groups")) TRAITS_NOTE = ("Each reading is what the cited studies found on average in the people they studied, not a " "diagnosis. A row marked ancestry reads differently in other populations; its note says how.") APOE_WARNING = ("APOE and Alzheimer's disease: a risk factor, not a diagnosis. Many people choose not to learn " "their APOE result; docs/42-traits.md explains it.") EXOMISER_NOTE = ("A ranking to bring to a clinical geneticist, not a diagnosis: a high score means a rare, likely " "damaging variant in a gene linked to symptoms like these, not that it causes them, and an empty or " "low list does not rule a genetic cause out. Coding and splice variants only (docs/48-exomiser.md).") ANCIENT_NOTE = ("Closeness on this PCA is genetic similarity, not descent: a genome near an ancient group shares " "ancestry with it and does not descend from those people. qpAdm models are not part of step 44; " "docs/44-ancient.md says how to read the plot.") def ancient_lines(d): """Step 44's lines, the same in both reports.""" lines = [f"AADR {d.get('release', '.')}: {d.get('sites_used', '.')} of {d.get('panel_sites', '.')} sites used; " f"axes from {d.get('present_day_people', '.')} present-day West Eurasians, " f"{d.get('ancient_people', '.')} ancient people in {d.get('ancient_groups', '.')} groups projected.", "Nearest ancient groups:"] lines += [f" {r['rank']:>2}. {r['group']} ({r['dates']}, {r['country']}; {r['n']} people)" for r in (d.get("nearest") or [])[:10]] return lines COUPLE_NOTE = ("A screen, not a diagnosis: the couple report (couple__.md in the family folder) lists the " "genes, variant types and repeats it does not see. These counts are of its gene table: a carrier " "deletion allele from read depth (step 35), and a possible shared risk it adds, is in that report " "only. See a genetic counsellor before acting on a result, or on its absence (docs/39-couple.md).") PRS_ANCESTRY_NOTE = ("Most PRS scores were developed in European-ancestry populations and predict less well for " "other ancestries, even with an ancestry-adjusted percentile.") # The caveats of the sections that had none, printed by both reports and the live site. PHARMCAT_NOTE = ("PharmCAT calls star alleles and phenotypes from the variants this genome holds in the genes it " "covers. A variant it cannot see (a deletion, a duplication, a hybrid gene outside CYP2D6) is not in " "its answer. Its drug guidance is for a prescriber to read with you: never change a medicine on " "this report alone.") CPIC_NOTE = ("CPIC recommendations follow the phenotype PharmCAT called. They are guidance for prescribers, not a " "prescription. A gene that was not called has no recommendation here, and that is not the same as a " "typical response.") PGX_CALLERS_NOTE = ("CYP2D6 sits beside its look-alike CYP2D7, and short reads often cannot tell them apart, so " "pypgx, Cyrius and step 36 can disagree or give no call. A disagreement or a missing call means " "the gene was not read reliably here; a clinical CYP2D6 test settles it.") CPSR_NOTE = ("CPSR grades variants in cancer predisposition genes with ACMG rules. A pathogenic or likely pathogenic " "row is something to take to a clinical geneticist, not a diagnosis. No row does not rule out an " "inherited cancer risk: large deletions, genes outside its panel and family history are not part of " "this screen.") VNTYPER_NOTE = ("The MUC1 repeat is long and GC-rich, and short reads cover it unevenly. VNtyper looks only for " "known frameshifts in it: a negative result lowers the chance of those and does not rule out " "ADTKD-MUC1, and a positive one needs a clinical test (SNaPshot for dupC) to confirm it.") SV_CALLERS_NOTE = ("Short reads find large deletions and duplications better than insertions and inversions, and " "the callers disagree on many events. The totals count every call, most of them common in the " "population; only the AnnotSV class 4 and 5 rows are graded for disease.") COVERAGE_NOTE = ("Mean depth is an average over the genome: some genes get far fewer reads, and the gene " "callability card lists those. The sex, identity and contamination checks catch a swapped or " "mixed sample, not every lab error.") VARIANTS_NOTE = ("Counts of the calls DeepVariant made against the reference. A whole genome usually holds 4 to 5 " "million, most of them common. PASS calls passed the caller's filter; a count says nothing about " "health on its own.") LPA_NOTE = ("The KIV-2 repeat count from read depth is a research estimate, not an Lp(a) level: the level is a " "blood test, and the count explains only part of the difference between people.") def combined_cell(h): """A ClinVar hit's combined-allele note (step 6), "" when it has none.""" note = h.get("combined_allele", ".") return "" if note in (".", "") else note def cdna_text(h): """Step 06's cDNA read check of one ClinVar hit, as both reports print it. A hit at a known construct site always shows its read counts.""" c = h["cdna"] counts = (f"{c['alt_clipped']} of {c['alt_reads']} alt reads and {c['ref_clipped']} of " f"{c['ref_reads']} ref reads clipped at an exon edge") site = f"known lab-construct site ({c['construct']}): " if c.get("construct") else "" if c["check"] == "flagged": return f"{site}{c['note']} ({counts})" if c["check"] == "clear": return f"{site}clear ({counts})" if site else "clear" out = site + "not checked" + (f": {c['note']}" if c["note"] else "") # A construct-site hit prints its counts whatever the verdict, when they were measured. return out + (f" ({counts})" if site and c.get("alt_reads") is not None else "") def construct_past_cap(hits, shown=50): """Hits at a known lab-construct site below the listed first `shown`: both reports print them too, so every hit the overview counts has a row.""" return [h for h in hits[shown:] if (h.get("cdna") or {}).get("construct")] def construct_past_cap_text(h): return f"{h['gene']} {h['chrom']}:{h['pos']} {h['ref']}>{h['alt']} {h['genotype']}: {cdna_text(h)}" CDNA_SCAN_NOTE = ("A locus with reads that jump from one exon to the next is spliced DNA: cDNA or plasmid " "contamination, or a processed copy of the gene the person carries. Check the reads before " "trusting a variant call there.") DEEP_INTRONIC_NOTE = ("Known pathogenic deep intronic sites, reported on every run: they lie far from any exon, so " "most filters miss them. 'ref' with a GQ is a reference call, 'ref (low confidence)' " "one below the call floor; 'no call' says nothing either way.") def cdna_scan_lines(d): """Step 06's genome-wide cDNA scan, as both reports print it ([] when it did not run).""" scan = d.get("cdna_scan") if scan is None: return [] loci = scan["loci"] if scan["note"].startswith("not run"): return [f"cDNA scan of every exon: {scan['note']}"] # The note says what was read (exon regions, contigs): a BAM short of contigs is no whole-exome negative. out = [f"cDNA scan of every exon: {len(loci)} loci with reads across two or more exon junctions" + (f" ({scan['note']})" if scan["note"] else "")] out += [f" {x['chrom']}:{x['start']}-{x['end']}: {x['junctions']} junctions, {x['reads']} reads" for x in loci[:20]] return out def deep_intronic_call(x): """One always-report site's call: 'het, GQ 40, DP 30', 'ref, GQ 50 (gVCF block)', 'no call: why'.""" if x["call"] == "no call": return "no call" + (f": {x['detail']}" if x["detail"] else "") return x["call"] + (f", {x['detail']}" if x["detail"] else "") def af_text(h): """A ClinVar hit's gnomAD allele frequency (from step 13's VEP output), as both reports print it; "" for a summary written before the field.""" if "af" not in h: return "" if h["af"] is None: return "gnomAD AF unknown" txt = f"gnomAD AF {h['af']:.3g}" return txt + ("; common: unlikely to be a high-penetrance finding" if h.get("common") else "") def call_text(h, floor=None): """The low-confidence mark of a ClinVar or CPSR row, "" for a confident one.""" if not h.get("low_confidence"): return "" vals = ", ".join(f"{k} {h[k.lower()]}" for k in ("GQ", "DP") if h.get(k.lower()) is not None) return f"low-confidence call ({vals}): check the reads" def high_rare(sf): """The secondary-findings HIGH-impact records counted as rare: neither a weak call nor of unknown frequency (a summary written before those marks counts every record).""" return sf.get("high_impact_rare", len(sf["high_impact"])) def high_apart(sf): """The HIGH-impact records listed but not counted as rare, "" without any.""" parts = [] if sf.get("high_impact_weak"): parts.append(f"{sf['high_impact_weak']} weak call(s)") if sf.get("high_impact_frequency_unknown"): parts.append(f"{sf['high_impact_frequency_unknown']} of unknown frequency") return f" (listed apart: {', '.join(parts)})" if parts else "" def high_marks(x, lead): """The marks of one HIGH-impact record (unknown frequency, weak call), each after lead (" (" closes with ")"), "" for a rare record with a sound call.""" marks = [] if x.get("frequency_unknown"): marks.append("frequency unknown, not counted as rare") if x.get("weak_call"): marks.append(f"weak call ({x.get('call_note')}): check the reads") if not marks: return "" return lead + "; ".join(marks) + (")" if lead.endswith("(") else "") def clinvar_floor_line(d): """How many ClinVar hits fall below step 6's call floor, or None for a summary written before the floor.""" if "low_confidence" not in d: return None f = d.get("call_floor") or {} return (f"Low-confidence calls (GQ below {f.get('GQ')} or DP below {f.get('DP')}), listed but not counted " f"above: {d['low_confidence']}") def clinvar_freq_line(d): """Where the hits' gnomAD frequencies came from, or why there are none.""" fr = d.get("frequency") if not fr: return None if fr.get("note"): return f"gnomAD AF: unknown for every hit ({fr['note']})" common = sum(1 for h in d.get("hits", []) if h.get("common")) return f"gnomAD AF from {fr['source']}: {common} hit(s) above {fr['common_af']:.0%}" def cpsr_row_text(x): """One CPSR P/LP or disagreement row: variant, gene, the classes and codes.""" parts = [f"final {x['final']}" + (f" ({x['authority']})" if x.get("authority") else "")] if x.get("clinvar"): parts.append(f"ClinVar {x['clinvar']}") if x.get("cpsr"): parts.append(f"CPSR's own {x['cpsr']}" + (f" ({x['acmg_codes']})" if x.get("acmg_codes") else "")) return f"{x['gene']} {x['variant']}: " + ", ".join(parts) def cpsr_lines(d, dbs): """The CPSR lines both reports share beyond the breakdown: the two ClinVar releases, CPSR's own benign calls among the final P/LP rows, the rows where CPSR and ClinVar disagree, the low-confidence rows and the cDNA flag.""" out = [] if "plp" not in d: return out out.append(f"ClinVar release in CPSR's bundle: {dbs.get('cpsr_clinvar_release') or 'unknown'}; " f"step 6 used the ClinVar file of {dbs.get('clinvar_release') or 'unknown'}") if d.get("own_class_column"): out.append(f"Final P/LP rows that CPSR's own rules class benign or likely benign: {d['final_plp_own_benign']}") out.append(f"Rows where ClinVar and CPSR's own class disagree on P/LP: {len(d['disagreements'])}") out += [" " + cpsr_row_text(x) for x in d["disagreements"]] else: out.append("The classification table has no CPSR_CLASSIFICATION column, so no disagreement can be shown.") out.append(f"P/LP rows below the depth floor (DP below {d['call_floor_dp']}): {d['low_confidence']}") out += [" " + cpsr_row_text(x) + f"; {call_text(x)}" for x in d["plp"] if x.get("low_confidence")] if "cdna_flagged" in d: out.append(f"cDNA read check of the P/LP rows (alt reads clipped at exon edges): {d['cdna_flagged']} flagged") out += [" " + cpsr_row_text(x) + f"; reads: {cdna_text(x)}" for x in d["plp"] if x["cdna"]["check"] == "flagged"] return out def hla_text(locus): """One HLA locus: each allele with its T1K quality, and the low-confidence mark. A quality-0 allele with more than collect_summary.HLA_MAX_CANDIDATES candidates reads 'no confident call'; the HFE row carries its label.""" q = locus.get("quality") or [] n = locus.get("candidates") or [] parts = [] for i, a in enumerate(locus["alleles"]): qi = q[i] if i < len(q) else "" if (i < len(n) and n[i] > collect_summary.HLA_MAX_CANDIDATES and qi != "" and collect_summary.hla_quality(qi) <= 0): parts.append(f"no confident call ({n[i]} candidates, quality {qi})") else: parts.append(a + (f" (quality {qi})" if qi != "" else "")) txt = " / ".join(parts) or "no call" if locus.get("low_confidence"): txt += "; low confidence (T1K quality 0 or below)" if locus.get("withheld_from_pharmcat"): txt += ", not passed to PharmCAT" if locus.get("label"): txt += f" [{locus['label']}]" return txt HLA_DERIVED_NOTE = ("Information about alleles, not a diagnosis: each line is an association reported in the cited " "study. Carrying an allele does not mean the condition or reaction will happen, and not carrying " "it does not rule it out. The genotypes are unphased.") KIR_NOTE = ("KIR genotypes as T1K typed them. No step interprets them: they matter for transplant matching and " "some immune conditions, not for drug guidance.") OT_AGREE = {"yes": "agree", "no": "disagree"} def hla_optitype_lines(ot): """Step 08's OptiType check, both reports: (gene, line) per class I gene, or one ('', line) with the reason the callers were not compared.""" if not ot["genes"]: return [("", f"not compared: {ot['reason']}")] out = [] for g in ot["genes"]: line = f"{OT_AGREE.get(g['agree'], g['agree'] or 'not compared')}: T1K {g['t1k']}, OptiType {g['optitype']}" if g["note"] not in ("", "-"): line += f" ({g['note']})" out.append((g["gene"], line)) return out def kir_lines(kir): """Step 08's KIR genes, both reports: (gene, alleles) per typed gene, then ('', line) for the genes with no allele, or the reason nothing was typed.""" if kir["reason"]: return [("", kir["reason"])] out = [(g["gene"], " / ".join(a + (f" (quality {q})" if q != "" else "") for a, q in zip(g["alleles"], g["quality"]))) for g in kir["typed"]] if kir["not_called"]: out.append(("", "No allele called (absent, or too few reads): " + ", ".join(kir["not_called"]))) return out def hla_derived_lines(d): """The derived HLA lines both reports print: the coeliac DQ line, the DQB1*02 dose and the allele table (bin/hla_alleles.tsv), present ones first.""" if not d: return [] c = d.get("coeliac") or {} if c.get("status") == "derived": dq25 = c["dq2_5"] + (f", {c['dq2_5_phase']}" if c.get("dq2_5_phase") else "") out = [f"Coeliac DQ: DQ2.5 {dq25}; DQ2.2 {c['dq2_2']}; DQ8 {c['dq8']}"] else: out = [f"Coeliac DQ: not determined ({c.get('reason') or 'no DQA1 and DQB1 call'})"] dose = c.get("dqb1_02_dose") out.append(f"DQB1*02 copies: {dose if dose is not None else 'not determined'}") order = {"present": 0, "uncertain": 1, "absent": 2, "not_determined": 3} for a in sorted(d.get("alleles") or [], key=lambda x: order.get(x["state"], 9)): state = a["state"].replace("_", " ") + (f" ({a['reason']})" if a.get("reason") else "") out.append(f"{a['allele']} {state}: {a['association']} ({a['citation']})") return out def cyp2d6_verdict(c): """Step 36's CYP2D6 verdict as one line, or '' without its table.""" v = c.get("consensus") if not v: return "" where = "passed to PharmCAT" if v.get("passed_to_pharmcat") else "not passed to PharmCAT" return f"{v.get('result') or '?'}, {where} ({v.get('reason') or 'no reason given'})" # The PharmCAT column is not a third caller: PharmCAT calls no CYP2D6 from a # VCF, it shows the call step 36 passed to it. CYP2D6_LABELS = {"PharmCAT": "PharmCAT (step 36's call)"} # Why step 32 could not call a gene on this reference. NOT_CALLABLE_WHY = {"GSTT1": "GRCh38 has it only on the ALT contig chr22_KI270879v1_alt, " "which a reference without ALT contigs lacks"} def probable_text(p): """The probable CYP2D6 call (pgx_outside_calls.probable_cyp2d6) as one line.""" return (f"{p.get('diplotype')}" + (f", {p['phenotype']}" if p.get("phenotype") else "") + "; not passed to PharmCAT, so no drug guidance rests on it") def pypgx_lines(d): """Step 32's lines below its counts, the same in both reports: the genes this reference cannot hold, the calls resting on a low-GQ variant, and the CYP2D6 depth check with its MAPQ shares.""" lines = [] for g in d.get("not_callable", []): lines.append(f"Not assessable on this reference: {g} ({NOT_CALLABLE_WHY.get(g, 'see docs/32-pypgx.md')})") for x in d.get("low_gq", []): lines.append(f"Low-confidence: {x['gene']} {x['diplotype']} rests on {x['weakest'] or 'a low-GQ variant'}: " "check the reads") dc = d.get("depth_check") if dc: nm = "not measured" lines.append(f"CYP2D6 depth check: {dc.get('status') or 'unreadable'}; share of the depth at MAPQ >= 1 / >= 20: " f"Cyrius's region with REP6 {dc.get('gene_mapq1_share', nm)} / {dc.get('gene_mapq20_share', nm)}, " f"gene body without REP6 {dc.get('body_mapq1_share', nm)} / {dc.get('body_mapq20_share', nm)}") return lines def pgx_copy_number(S): """(gene, copy number) rows, the same in both reports: pypgx's call from read depth for each BAM-mode gene of assets/pgx_genes.tsv (UGT2B17 among them), or the reason it has none.""" pg = S.get("pypgx", MISSING) return [(g, f"{v} (pypgx, read depth)") for g, v in (pg["data"].get("cnv_call") or {}).items()] # A section the summary lacks (one written before the section existed). MISSING = {"title": "", "state": "missing", "note": None, "data": {}} SEX_CHECK_AGREE = "declared and measured sex agree" def freemix_text(q): """FREEMIX with its verdict, as both reports print it.""" if q.get("contamination") == "not_run" or not q.get("freemix"): return "not run" warn = q.get("freemix_warn_above", "") few = ("; fewer than 1,000 panel markers had reads, so VerifyBamID2 ran without its marker check" if q.get("verifybamid2_marker_check") == "skipped" else "") if q.get("contamination") == "warn": return f"{q['freemix']} (above {warn}: possible contamination, see docs/33-sample-qc.md{few})" return f"{q['freemix']} (warning above {warn}{few})" MOSAIC_NOTE = ("Loss of chrY in a share of the blood cells of men, and of one chrX in women, becomes more common " "with age. Population studies link loss of Y with smoking and with higher rates of heart disease " "and some cancers; loss of X is less studied. That is a population-level association, not a " "diagnosis for one person. Below about 10% of the cells nothing can be told at 30x " "(docs/33-sample-qc.md).") MOSAIC_CALL = {"detected": ("detected", "yellow"), "not_detected": ("not detected above 10%", "gray"), "gain": ("an extra copy, not a loss", "yellow"), "not_estimated": ("not estimated", "gray")} def pct(x): return f"{x * 100:.1f}%" if isinstance(x, (int, float)) else "?" def callability_gene(g): if g["status"] == "not on this reference": return f"{g['gene']} (not on this reference)" return f"{g['gene']} ({100 * g['share']:.0f}%)" def callability_lines(d): """Step 16b's gene callability: the lines of the text section and the card.""" out = [f"{d['read']} of the {d['catalog_genes']} hard-to-read genes of assets/callability_genes.tsv were read: " f"{100 * d['min_share']:.0f}% or more of their bases had {d['min_depth']} or more reads of mapping " f"quality {d['min_mapq']} or more."] nr, owned = d["not_read"], d["not_read_owned"] out.append(f"Not read, and no other step calls them ({len(nr)}): " + (", ".join(callability_gene(g) for g in nr) if nr else "none")) if owned: out.append(f"Not read here, called by a step of their own ({len(owned)}): " + ", ".join(f"{callability_gene(g)} by {g['owner']}" for g in owned)) return out def mosaic_lines(q): """The estimate from depth and from chrX allele fractions, one line each, as both reports print them.""" what = "the Y" if q.get("chrom") == "chrY" else "one X" out = [] if isinstance(q.get("loss_depth"), (int, float)): ratio = q.get("depth_ratio") ratio = f"{ratio:.3f}" if isinstance(ratio, (int, float)) else "?" out.append(f"From depth: estimated share of the cells that lost {what} {pct(q['loss_depth'])} (95% range " f"{pct(q.get('loss_depth_low'))} to {pct(q.get('loss_depth_high'))}); {q.get('chrom')} to " f"autosome depth ratio {ratio}, {q.get('depth_ratio_expected')} expected") if isinstance(q.get("loss_af"), (int, float)): out.append(f"From chrX allele fractions at {q.get('x_het_sites')} heterozygous sites: {pct(q['loss_af'])} " f"(95% range {pct(q.get('loss_af_low'))} to {pct(q.get('loss_af_high'))})") return out def read_count_text(d): """Step 02's two counts as one line, in both reports.""" txt = f"{d['input_reads']} reads in, {d['primary_records']} primary records in the BAM" if d.get("read_count_check") == "mismatch": m = d["missing_reads"] txt += (f": {m} reads missing" if m > 0 else ": more records than reads in") + \ " (the BAM was kept by the warn setting, see docs/troubleshooting.md)" return txt def prs_chrx_note(d): """A sentence when chrX rows of a score were left out (no sex given), else ''.""" left = [f"{r['pgs_id']} ({r['chrx'].split()[0]})" for r in d.get("scores", []) if (r.get("chrx") or "").endswith("left out")] if not left: return "" return (f" Rows on chrX were left out, because the sample's sex was not given: {', '.join(left)}. " "Give the sex to score them (docs/25-prs.md).") PRS_NOT_APPLICABLE = "not applicable to the declared sex" def prs_percentile(r): """The percentile cell of a PRS row in both reports: the percentile with its group, 'not applicable to the declared sex' for a score of the other sex (it has no percentile), or '' when there is none.""" if r.get("sex_check") == PRS_NOT_APPLICABLE: return f"{PRS_NOT_APPLICABLE} ({r.get('applies_to') or 'sex'}-specific score)" if r.get("percentile"): return f"{r['percentile']} ({r.get('group') or 'group unknown'})" return "" def prs_effect(r): """The effect cell of a PRS row in both reports: the odds or hazard ratio the PGS Catalog records for the score in the sample's group ("HR 1.53 (EUR, PPM000591)"), a line saying the score has none for that group, or '' when the sample has no group (no panel, or no percentile), the score does not apply to the declared sex, or the table names no evaluations.""" if r.get("evaluated_in") is None: return "" if r.get("percentile") and r.get("group") and r.get("sex_check") != PRS_NOT_APPLICABLE: if r.get("effect"): return r["effect"] where = f"; evaluated in {', '.join(r['evaluated_in'])}" if r.get("evaluated_in") else "" return f"no published OR or HR for {r['group']}{where}" return "" # Part of the PRS caption sentence (prs_note), so not a *_NOTE caveat of its own. PRS_EFFECT_TEXT = ("Effect: the odds ratio (OR) or hazard ratio (HR) a published evaluation of the score measured " "in people of the same reference group, in that evaluation's unit (its PGS Catalog PPM page says " "which). It describes the score in that group, not your own risk, and is shown only for a group " "the score was evaluated in.") def prs_sex_note(d): """A sentence naming the sex-specific scores when no sex was declared, else ''.""" named = [f"{r['pgs_id']} ({r['applies_to']})" for r in d.get("scores", []) if r.get("sex_check") == "no sex declared" and r.get("applies_to")] if not named: return "" return (f" No sex was declared, so these sex-specific scores are shown for any sex: {', '.join(named)}. " "Give the sex to mark a score of the other sex not applicable (docs/25-prs.md).") def prs_note(d): """The line under the PRS scores, in both reports: what the numbers can be compared with.""" x = prs_chrx_note(d) + prs_sex_note(d) if d.get("adjusted"): anc = d.get("ancestry") or {} group = anc.get("population") or next((r.get("group") for r in d["scores"] if r.get("group")), "") panel = f" of the {anc['panel']} reference panel" if anc.get("panel") else " of the reference panel" low = " The ancestry match is low-confidence: read the percentile with care." if anc.get("low_confidence") == "True" else "" eff = f" {PRS_EFFECT_TEXT}" if any(r.get("evaluated_in") is not None for r in d["scores"]) else "" return (f"Percentile: where the score falls among the {group or 'most similar'} samples{panel}, " f"the group whose genetic ancestry is most similar to this sample's (pgsc_calc).{low} " f"A percentile is not a risk.{eff} {PRS_ANCESTRY_NOTE} See docs/25-prs.md." + x) return ("Raw score only: no ancestry reference panel was installed, so there is no percentile and the sum " f"cannot be compared with anyone (scripts/setup.sh --ancestry-panel adds it). {PRS_ANCESTRY_NOTE} " "See docs/25-prs.md." + x) # --- text ------------------------------------------------------------------------ def couple_lines(d): """Step 39's lines, the same in both reports: the counts, then each shared and X-linked gene with the chance for a child and both partners' findings.""" partner = d.get("partner") or "the partner" lines = [f"Partner: {partner}. Genes where both carry a change: {len(d.get('shared', []))}; X-linked " f"findings: {len(d.get('x_linked', []))}; genes where only one partner carries a change: " f"{d.get('one_partner', 0)}"] for label, key in (("Shared", "shared"), ("X-linked", "x_linked")): for x in d.get(key, []): lines.append(f"{label}: {x['gene']} ({x['condition']}): {x['risk']}. This sample: {x['own']}. " f"{partner}: {x['partner_findings']}") return lines + [COUPLE_NOTE] def share(x): """A fraction as a whole percentage, for the fine-grained ancestry section.""" return "." if x is None else f"{100 * x:.0f}%" def ancestry_fine_rows(d, level): """The groups of one level worth a line: every continental group of 1% or more, a regional one of 1% or more or whose bootstrap range reaches 5%.""" return [r for r in d.get(level, []) if r["fraction"] is not None and (r["fraction"] >= 0.01 or (level == "region" and (r.get("high") or 0) >= 0.05))] def ancestry_fine_spread(r): return f" ({share(r['low'])} to {share(r['high'])})" if r.get("low") is not None else "" def ancestry_fine_left_out(d): """The groups the model leaves out, as one sentence, or ''.""" if not d.get("left_out"): return "" # One TSV row per level ("Oceania (continental group)"); merge a group the # two levels share into one name, as the step's own summary does. kinds = {} for r in d["left_out"]: m = re.fullmatch(r"(.*) \((.*) group\)", r["group"]) name, kind = (m.group(1), m.group(2)) if m else (r["group"], "") kinds.setdefault(name, []) if kind and kind not in kinds[name]: kinds[name].append(kind) names = [f"{n} ({' and '.join(k)} group)" if k else n for n, k in kinds.items()] return (f"Left out of the model: {', '.join(names)}. The panel has fewer than " f"{d.get('min_references', 10)} unrelated reference people for it, so its ancestry is spread over the " "groups shown.") def ancestry_fine_painted(d): """The painted shares, or why there are none, and the chromosomes RFMix failed on.""" failed = ", ".join(r["code"] for r in d.get("not_painted", [])) if d.get("painting"): text = ", ".join(f"{r['group']} {share(r['fraction'])}" for r in d["painting"]) else: text = "none" + ("" if failed else " (no chromosome long enough)") return text + (f"; not painted: RFMix failed on {failed}" if failed else "") def exomiser_terms(d): return ", ".join(f"{t['label']} ({t['id']})" if t.get("label") else t["id"] for t in d.get("terms", [])) or "." def exomiser_text(d, sample): """The Exomiser section of the text report: the terms, then each rank.""" out = [f" Symptoms searched: {exomiser_terms(d)}"] if not d["genes"]: out.append(" No gene passed Exomiser's filters with a variant that fits a mode of inheritance.") for g in d["genes"]: out.append(f" {g['rank']}. {g['gene']} ({g['moi']}) score {g['exomiser_score']} (symptom match {g['phenotype_score']})") for v in g["variants"]: out.append(f" {v['variant']} {v['genotype']} {v['consequence']} {v['hgvs']} ACMG {v['acmg']}" + (f"; {v['disease']}" if v["disease"] != "." else "")) out.append(f" {EXOMISER_NOTE} In words: exomiser/{sample}_exomiser.txt") return out def exomiser_html(d, sample): """The Exomiser card's body: one table row per rank and variant.""" rows = [] for g in d["genes"]: for i, v in enumerate(g["variants"]): lead = (f"{E(g['rank'])}{E(g['gene'])}{E(g['moi'])}{E(g['exomiser_score'])}" f"{E(g['phenotype_score'])}") if i == 0 else "" * 5 rows.append(f" {lead}{E(v['variant'])} {E(v['genotype'])}
{E(v['consequence'])} {E(v['hgvs'])}{E(v['acmg'])}" f"{E(v['disease'])}{viewer_td_of(v['variant'])}") body = [stat("Symptoms searched", E(exomiser_terms(d)))] if rows: body += [" ", " " "" f"{VIEWER_TH}"] body += rows + ["
RankGeneInheritanceScoreSymptom matchVariantACMG (Exomiser)Linked disease
", VIEWER_NOTE] else: body.append(stat("Ranked genes", "none passed Exomiser's filters")) body += [small_note(EXOMISER_NOTE), small_note(f"Exomiser's own report: exomiser/{sample}_exomiser.html")] return body def traits_text(d, sample): """The traits section of the text report: the rows read, the ones not read, and the APOE lines last, after a warning.""" out = [f" Read: {d['called']} No genotype at the position: {d['not_covered']} Other allele: {d['other_allele']}"] for r in d["rows"]: if r["status"] == "not_covered": continue mark = " [ancestry]" if r["ancestry"] == "yes" else "" out.append(f" {r['trait']} ({r['gene']} {r['rsid']}): {r['genotype']}{mark}. {r['reading']} (PMID {r['pmids']})") missing = [r["rsid"] for r in d["rows"] if r["status"] == "not_covered"] if missing: out.append(f" Not read (no genotype in the gVCF): {', '.join(missing)}") out.append(f" {TRAITS_NOTE} Notes per row: traits/{sample}_traits.tsv") if d.get("rules"): out.append(f" Genotype rules (several sites read together; traits/{sample}_genotype_rules.tsv):") for r in d["rules"]: out.append(f" {r['trait']} ({r['gene']} {r['rsids'].replace(',', ', ')}): {rule_result(r)}. " f"{r['reading']} (PMID {r['pmids']})") if r.get("g2"): out.append(f" With G2 (rs71785313): {g2_result(r)}. {r['g2']['text']} {r['g2']['reading']}") if d.get("apoe"): out.append(f" {APOE_WARNING}") for r in d["apoe"]: out.append(f" {r['trait']} ({r['rsid']}): {r['genotype']}. {r['reading']}") return out RULE_PHASE_TEXT = {"read_backed": "phased from the reads", "not_needed": "no phase needed", "not_used": "phase not used", "unphased": "not phased"} def rule_result(r): """A genotype rule's result: its label when called, else its status; and how it was phased.""" res = r["result"] if r["status"] == "called" else r["status"].replace("_", " ") ph = RULE_PHASE_TEXT.get(r["phase"]) return res + (f" ({ph})" if ph else "") def g2_result(r): """The APOL1 rule's result with G2 (collect_summary's g2), or None for any other rule.""" g2 = r.get("g2") if not g2: return None return g2["result"] if g2["result"] != "." else "not read" def g2_result_html(r): res = g2_result(r) return f"
With G2: {E(res)}" if res else "" def g2_reading_html(r): g2 = r.get("g2") if not g2: return "" return f"
With G2: {E(g2['reading'])}
{E(g2['text'])}" def rules_html(d, sample): """The genotype rules table of the traits card.""" rows = [] for r in d.get("rules") or []: anc = " " + badge("ancestry", "yellow") if r["ancestry"] == "yes" else "" rows.append(f" {E(r['trait'])}{E(r['gene'])}
" f"{E(r['rsids'].replace(',', ', '))}{E(r['genotypes'].replace(',', ', '))}" f"{E(rule_result(r))}{anc}{g2_result_html(r)}{E(r['reading'])}{g2_reading_html(r)}" f"
" f"{E(r['note'])}PMID {E(r['pmids'])}") if not rows: return [] return ["

Genotype rules (several sites read together)

", " ", " " ""] + rows + ["
TraitGene and sitesGenotypesResultReadingSource
", small_note(f"Every rule line: traits/{sample}_genotype_rules.tsv")] def traits_html(d, sample): """The traits card's body: one table row per table row read or not read, and the APOE lines folded away behind a warning.""" def tr(r): anc = " " + badge("ancestry", "yellow") if r["ancestry"] == "yes" else "" return (f"{E(r['trait'])}{E(r['gene'])}
" f"{E(r['rsid'])}{E(r['genotype'])}{anc}{E(r['reading'])}" f"
{E(r['note'])}PMID {E(r['pmids'])}") head = " TraitGeneGenotypeReadingSource" body = [stat("Read / no genotype / other allele", E(f"{d['called']} / {d['not_covered']} / {d['other_allele']}")), " ", head] + [" " + tr(r) for r in d["rows"]] + ["
", small_note(TRAITS_NOTE)] body += rules_html(d, sample) if d.get("apoe"): body += [f"
{E(APOE_WARNING)} Open to show it.", " ", head] body += [" " + tr(r) for r in d["apoe"]] + ["
"] body.append(small_note(f"Every row with its note: traits/{sample}_traits.tsv")) return body COMPHET_NOTE = ("A pair can hit both copies of the gene only in trans. cis: one copy carries both variants. " "unknown: fewer than 2 reads or read pairs cover both positions, the reads disagree, or there is no BAM; " "the pairs table gives the reason. A parent's genome or long reads can phase it. " "Every pair: slivar/_compound_het_pairs.tsv") def comphet_phase_text(d): """Step 31's phase of the compound-het pairs, as text lines.""" ph = d["compound_het_phase"] lines = [f" Phase from the reads: {ph.get('trans', 0)} trans, {ph.get('cis', 0)} cis, " f"{ph.get('unknown', 0)} unknown of {d.get('compound_het_pairs', 0)} pairs"] for x in d.get("compound_het_trans") or []: lines.append(f" {x['gene']:<8} {x['variants']} in trans on {x['reads']} reads or read pairs") if ph.get("trans", 0) > len(d.get("compound_het_trans") or []): lines.append(f" ... {ph['trans'] - len(d['compound_het_trans'])} more in the pairs table") return lines + [f" ({COMPHET_NOTE})"] def comphet_phase_html(d): """The same, for the slivar card.""" ph = d["compound_het_phase"] out = [stat("Pairs in trans / cis / unknown", f"{ph.get('trans', 0)} / {ph.get('cis', 0)} / {ph.get('unknown', 0)}")] trans = d.get("compound_het_trans") or [] if trans: out += [" ", f" {VIEWER_TH}"] out += [f" " f"{viewer_td_of(x['variants'])}" for x in trans] out += ["
GenePair in transReads
{E(x['gene'])}{E(x['variants'])}{E(x['reads'])}
", VIEWER_NOTE] return out + [small_note(COMPHET_NOTE)] ANNOTSV_NOTE = ("A class 4 or 5 SV made by one caller, a deletion on the exon edges of a transcript (the reads of " "a processed transcript or cDNA aligned across an intron) or one at 1% or more in AnnotSV's benign " "set is unlikely to be a rare pathogenic SV: check the reads before acting on it (docs/05-annotsv.md). " "Step 05's rules (assets/sv_rule_regions.tsv and the read-depth check) move a class 4 or 5 call to " "class 3 when it lies in a coding tandem repeat, an immunoglobulin or T-cell receptor locus or the " "MHC, names a pseudogene by a disease gene's alias, or its read depth does not show the change; " "those calls are listed apart with the reason and are not counted here.") def annotsv_support_text(x): if x["support"] is None: return "not known (no step 22 consensus)" if x["support"] == 1: return f"single caller ({x['caller']})" return f"{x['support']} callers ({', '.join(x['support_callers'])})" def annotsv_genes_text(x): g = x["genes"] return ", ".join(g[:3]) + (f" and {len(g) - 3} more" if len(g) > 3 else "") if g else "no gene" def annotsv_flags(x): """The exon-edge and population flags of one class 4-5 SV, as a list.""" out = [] if x["exon_edge"] == "yes": out.append("on exon edges: " + x["exon_edge_detail"]) elif x["exon_edge"] == "not checked": out.append("exon edges not checked") if x["population_af"] is not None: out.append(f"benign-set AF {x['population_af']:g}" + (f" ({x['population_source']})" if x["population_source"] else "") + (", common" if x["common"] else "")) if x.get("rule_detail") and str(x["acmg_class"]) in ("4", "5"): out.append(f"rule {x['rule']}: {x['rule_detail']}") return out def annotsv_moved_text(x): """One SV step 05's rules moved to class 3: where, from which class, and why.""" return (f"{x['type']} {x['sv']} {annotsv_genes_text(x)} AnnotSV class {x['annotsv_class']} -> " f"{x['acmg_class']} ({x['rule'] or 'rule not named'}: {x['rule_detail'] or 'no detail'})") def annotsv_lines(d): """Step 05's class 4-5 lines, the same in both reports.""" head = f"Class 4-5 SVs: {d['count']}" if d["count"]: head += (f" (single caller: {d['single_caller'] if d['consensus'] else 'not known'}; deletions on exon edges: " f"{d['exon_edge'] if d['exon_edge_checked'] else 'not checked'}; common: {d['common']})") lines = [head] if d.get("downgraded"): lines.append(f"Moved to class 3 by step 05's rules, not counted above: {len(d['downgraded'])}") if d["count"] and not d["consensus"]: lines.append(d.get("consensus_note") or "Caller support: step 22's consensus did not run, so how many callers " "saw each SV is not known.") return lines # --- chapters ---------------------------------------------------------------------- # Both reports in reading order. A chapter is (id, title, question, sections); # a section is (id, title, keys), the keys of collect_summary.SECTIONS whose # results it shows. Every key is in exactly one section, and a report that # writes for a key no section lists stops with a KeyError: a new step gets its # row here. The section ids are the HTML anchors; the titles are the table of # contents. The steps not run and the limits come after the last chapter. CHAPTERS = ( ("quality", "Quality", "Can I trust this data?", ( ("qc", "Quality control", ("coverage", "sex_check", "sample_qc", "read_count")), ("callability", "Genes this genome could not read reliably", ("callability",)), ("variants", "Variant calling", ("variants",)), )), ("clinical", "Clinical", "Is there anything to take to a doctor?", ( ("clinvar", "ClinVar screen and hits", ("clinvar",)), ("clinical-filter", "Clinical filter and secondary findings", ("clinical",)), ("cpsr", "Cancer predisposition", ("cpsr",)), ("slivar", "Variant prioritization", ("slivar",)), ("exomiser", "Symptom-driven ranking", ("exomiser",)), ("structural-variants", "Structural variants", ("manta", "delly", "cnvpytor", "sv_consensus", "annotsv")), ("mei", "Mobile element insertions", ("mei",)), ("expansions", "Repeat expansions", ("expansions",)), ("vntyper", "MUC1 repeat (ADTKD)", ("vntyper",)), ("mito", "Mitochondrial variants", ("mito",)), ("lpa", "Lp(a)", ("lpa",)), ("chip", "Clonal haematopoiesis", ("chip",)), ("mosaic", "Mosaic loss of chromosome Y or X", ("mosaic_sex_loss",)), ("mosaic-mca", "Mosaic chromosomal alterations", ("mosaic",)), )), ("carrier", "Carrier", "What could I pass on to a child?", ( ("carrier-list", "Carrier list", ("carrier",)), ("couple", "Couple carrier screen", ("couple",)), ("paralogs", "Paralog genes and SMN1", ("paralogs", "parascopy")), )), ("medicines", "Medicines", "How might I respond to medicines?", ( ("pharmcat", "PharmCAT", ("pharmcat",)), ("cpic", "CPIC recommendations", ("cpic",)), ("cyp2d6", "pypgx, Cyrius and CYP2D6", ("pypgx", "cyrius")), ("hla", "HLA typing", ("hla",)), ("locityper", "Locityper second opinion", ("locityper",)), )), ("ancestry", "Ancestry", "Where do my ancestors come from?", ( ("ancestry-fine", "Fine-grained ancestry", ("ancestry_fine",)), ("mt-haplogroup", "Mitochondrial haplogroup", ("haplogroup",)), ("y-chromosome", "Y chromosome", ("y_haplogroup", "y_tree", "y_str")), ("archaic", "Archaic ancestry", ("archaic",)), ("ancient", "Ancient populations", ("ancient",)), ("roh", "Runs of homozygosity", ("roh",)), )), ("traits", "Traits and scores", "What do studies say about my traits and risk scores?", ( ("traits-panel", "Traits", ("traits",)), ("prs", "Polygenic risk scores", ("prs",)), ("bloodtype", "Blood groups", ("bloodtype",)), ("telomere", "Telomere content", ("telomere",)), )), ("other", "Other and exports", "What else did the run find or write?", ( ("viral", "Viral DNA", ("viral",)), ("consumer-export", "Raw-data export", ("consumer_export",)), )), ) # The section id of each summary key. SECTION_OF = {k: sid for _, _, _, secs in CHAPTERS for sid, _, keys in secs for k in keys} # The caveats of each section, by constant name, in the order the card shows them: the first is the # one the live site shows under a card's title. caveat_notes() is unkeyed, so the live site # (bin/live_results.py) reads this map; tests/test_live_results.py checks every section id has one. SECTION_NOTES = { "qc": ("COVERAGE_NOTE", "KARYOTYPE_NOTE"), "callability": ("CALLABILITY_NOTE",), "variants": ("VARIANTS_NOTE",), "clinvar": ("CLINVAR_FREQ_NOTE", "CDNA_SCAN_NOTE", "DEEP_INTRONIC_NOTE"), "clinical-filter": ("ACMG_NOTE",), "cpsr": ("CPSR_NOTE",), "slivar": ("COMPHET_NOTE",), "exomiser": ("EXOMISER_NOTE",), "structural-variants": ("SV_CALLERS_NOTE", "ANNOTSV_NOTE", "CNVPYTOR_NOTE"), "mei": ("MEI_NOTE",), "expansions": ("EH_NOTE", "NOT_GRADED_NOTE", "RFC1_NOTE"), "vntyper": ("VNTYPER_NOTE",), "mito": ("MITO_NOTE", "MITO_POLYC_NOTE", "MITO_DELETION_NOTE", "MITO_COPIES_NOTE"), "lpa": ("LPA_NOTE",), "chip": ("CHIP_NOTE",), "mosaic": ("MOSAIC_NOTE",), "mosaic-mca": ("MCA_NOTE",), "carrier-list": ("CARRIER_NOTE",), "couple": ("COUPLE_NOTE",), "paralogs": ("PARASCOPY_NOTE", "PARALOG_NOTE", "PARASCOPY_LOCI_NOTE"), "pharmcat": ("PHARMCAT_NOTE",), "cpic": ("CPIC_NOTE",), "cyp2d6": ("PGX_CALLERS_NOTE",), "hla": ("HLA_NOTE", "HLA_DERIVED_NOTE", "KIR_NOTE"), "locityper": ("LOCITYPER_NOTE",), "ancestry-fine": ("ANCESTRY_FINE_NOTE",), "mt-haplogroup": ("EXPLORE_NOTE",), "y-chromosome": ("Y_TREE_NOTE", "YSTR_NOTE", "EXPLORE_NOTE"), "archaic": ("ARCHAIC_NOTE",), "ancient": ("ANCIENT_NOTE",), "roh": ("ROH_NOTE", "ROH_UPD_NOTE", "ROH_F_NOTE", "ROH_BAND_NOTE"), "traits-panel": ("TRAITS_NOTE",), "prs": ("PRS_ANCESTRY_NOTE",), "bloodtype": ("BLOODTYPE_NOTE",), "telomere": ("TELOMERE_NOTE",), "viral": ("VIRAL_NOTE",), "consumer-export": ("CONSUMER_NOTE",), } def section_keys(sid): return next(keys for _, _, _, secs in CHAPTERS for x, _, keys in secs if x == sid) def recheck_line(r): """One line of run facts from the last database re-check (bin/owngenome_recheck.py).""" newer = [i for i in r.get("items") or [] if i.get("class") not in ("no-newer-release", None)] head = f"Database re-check: {r.get('checked_utc') or 'unknown date'}: " if not newer: return head + "nothing newer than this run" return head + "; ".join(f"{i.get('label') or i.get('item')} {i.get('class')}" for i in newer) def text_report(s): S = s["sections"] # Each block writes into its section's list (at(key), or head(key)); # the lists are joined in CHAPTERS order at the end. parts = {"top": []} out = parts["top"] class Sink: def append(self, line): out.append(line) def extend(self, lines): out.extend(lines) def at(key): nonlocal out out = parts.setdefault(key if key in ("top", "end") else SECTION_OF[key], []) sink = Sink() w = sink.append w("=" * 80) w(" GENOMICS ANALYSIS REPORT") w(f" Sample: {s['sample']}") w(f" Generated: {s['generated_utc']}") if s["run"]["started_utc"]: w(f" Latest run-all.sh run: {s['run']['started_utc']}") if s.get("recheck"): w(f" {recheck_line(s['recheck'])}") ns = s.get("new_since") or {} w("=" * 80) w("") def head(key, title=None): sec = S.get(key, MISSING) at(key) if sec["state"] == "missing": return False w(f"## {title or sec['title']}") w("---") if key in (ns.get("sections") or []): w(f" [New since {ns.get('previous_utc') or 'the previous run'}]") note = stale_note(sec) if note: w(f" [{note}]") if sec["state"] == "failed": w("") return sec["state"] in ("ok", "stale") # QC at("coverage") cov, sexc, sqc = S["coverage"], S["sex_check"], S.get("sample_qc", MISSING) rdc = S.get("read_count", MISSING) if any(sec["state"] != "missing" for sec in (cov, sexc, sqc, rdc)): w("## Quality control") w("---") if any(k in (ns.get("sections") or []) for k in ("coverage", "sex_check", "sample_qc", "read_count")): w(f" [New since {ns.get('previous_utc') or 'the previous run'}]") for sec in (cov, sexc, sqc, rdc): if stale_note(sec): w(f" [{sec['title']}: {stale_note(sec)}]") md = cov["data"].get("mean_depth") w(f" Mean depth: {md:.1f}x" if isinstance(md, (int, float)) else " Mean depth: not available") if rdc["state"] in ("ok", "stale"): flag = " ** READS LOST IN ALIGNMENT **" if rdc["data"].get("read_count_check") == "mismatch" else "" w(f" Alignment: {read_count_text(rdc['data'])}{flag}") inferred = sexc["data"].get("inferred_sex") declared = s["run"]["declared_sex"] w(f" Inferred sex: {inferred or 'not available'}") w(f" Declared sex: {declared or 'not declared'}" + (" ** DOES NOT MATCH the inferred sex **" if inferred and declared and inferred != declared else "")) if sqc["state"] in ("ok", "stale"): q = sqc["data"] w(f" Sex from the reads (somalier): {q.get('inferred_sex')}" + (" ** DOES NOT MATCH the declared sex **" if q.get("sex_check") == "mismatch" else "") + (f" ({SEX_CHECK_AGREE})" if q.get("sex_check") == "ok" else "")) if q.get("sex_check") == "not_checked": w(f" not checked: {q.get('sex_check_reason')}") w(f" Contamination (VerifyBamID2 FREEMIX): {freemix_text(q)}") if q.get("same_person_as"): w(f" ** The same person as: {q['same_person_as']} (a duplicate or a sample swap) **") for line in karyotype_lines(S): w(f" {line}") w(f" {COVERAGE_NOTE}") w("") if head("callability", "Genes This Genome Could Not Read Reliably"): for line in callability_lines(S["callability"]["data"]): w(f" {line}") w(f" {CALLABILITY_NOTE}") w("") if head("mosaic_sex_loss"): q = S["mosaic_sex_loss"]["data"] w(f" {q.get('chrom') or 'chrY or chrX'}: {MOSAIC_CALL.get(q.get('call'), (q.get('call'), ''))[0]}" f" ({q.get('reason')})") for line in mosaic_lines(q): w(f" {line}") w(f" {MOSAIC_NOTE}") w("") if head("variants", "Variant Calling (DeepVariant)"): d = S["variants"]["data"] w(f" Total variants: {d['total']}") w(f" PASS variants: {d['pass']}") w(f" SNPs: {d['snps']} Indels: {d['indels']}") w(f" {VARIANTS_NOTE}") w("") if head("clinvar", "ClinVar Pathogenic Screen"): d = S["clinvar"]["data"] w(f" Pathogenic/Likely Pathogenic hits: {d['count']}") low = clinvar_floor_line(d) if low: w(f" {low}") w(f" ClinVar file date: {s['databases']['clinvar_release'] or 'unknown'}") if d["hits"]: by = d["by_stars"] w(" By review status: " + ", ".join(f"{k} star{'s' if k != '1' else ''} {by[k]}" for k in ("4", "3", "2", "1", "0"))) if "cdna_flagged" in d: w(f" cDNA read check (alt reads clipped at exon edges): {d['cdna_flagged']} flagged") freq = clinvar_freq_line(d) if freq: w(f" {freq}") w("") w(" Hits (best-reviewed first, up to 50): gene, position, genotype, significance [review status] stars") for h in d["hits"][:50]: note = combined_cell(h) w(f" {h['gene']:<10} {h['chrom']}:{h['pos']} {h['ref']}>{h['alt']} {h['genotype']} " f"{h['significance']} [{h['review_status']}] {h['stars']}*" + (f" ({note})" if note else "")) if af_text(h): w(f" frequency: {af_text(h)}") if call_text(h): w(f" call: {call_text(h)}") if "cdna" in h: w(f" reads: {cdna_text(h)}") extra = construct_past_cap(d["hits"]) if extra: w(" Hits at a known lab-construct site past the first 50:") for h in extra: w(f" {construct_past_cap_text(h)}") for line in cdna_scan_lines(d): w(f" {line}") if d.get("cdna_scan") and d["cdna_scan"]["loci"]: w(f" {CDNA_SCAN_NOTE}") if "deep_intronic" in d: w(" Known deep intronic sites (always reported): gene, variant, call") for x in d["deep_intronic"]: w(f" {x['gene']:<10} {x['hgvs']} {x['chrom']}:{x['pos']} {x['ref']}>{x['alt']} {deep_intronic_call(x)}") w(f" {DEEP_INTRONIC_NOTE}") w(f" {CLINVAR_FREQ_NOTE}") w("") if head("carrier", "Carrier List (this sample)"): for line in carrier_lines(S["carrier"]["data"]): w(f" {line}") w(f" {CARRIER_NOTE}") w("") if head("couple", "Couple Carrier Screen (step 39)"): for line in couple_lines(S["couple"]["data"]): w(f" {line}") w("") if head("pharmcat", "Pharmacogenomics (PharmCAT)"): d = S["pharmcat"]["data"] w(f" Report: {S['pharmcat']['source']} (PharmCAT {d.get('version') or 'version unknown'})") if d.get("html_report"): w(" HTML report beside it (open in a browser for full details)") w(f" {PHARMCAT_NOTE}") w("") if head("cpic", "CPIC Drug-Gene Recommendations"): d = S["cpic"]["data"] if d["parse_failed"]: w(" The PharmCAT report could not be parsed: see the CPIC report.") w(f" Genes with a non-normal phenotype: {d['non_normal']} More than one possible result: " f"{d.get('ambiguous', 0)} Not called: {d['not_called']} " f"Called without a function phenotype (no drug guidance): {d.get('unclassified', 0)}") for g in d["genes"]: if g["status"] in ("non-normal", "ambiguous"): w(f" {g['gene']:<10} {g['diplotype']:<28} {g['phenotype']}") for warn in d["warnings"]: w(f" WARNING: {warn}") w(f" Drugs per gene: {os.path.join(os.path.dirname(S['cpic']['source']), s['sample'] + '_cpic_recommendations.txt')}") w(f" {CPIC_NOTE}") w("") if head("pypgx", "pypgx Pharmacogenomics"): d = S["pypgx"]["data"] w(f" Genes called: {d['genes_called']}/{d['genes_total']}") w(f" CYP2D6 diplotype: {d['cyp2d6']}") if "comparison" in d: w(f" PharmCAT vs pypgx conflicts: {d['comparison']['conflicts']}") if d["comparison"]["one_tool_only"]: w(f" Scope differences (only one tool called): {d['comparison']['one_tool_only']}") for line in pypgx_lines(d): w(f" {line}") w("") at("pypgx") cn_rows = pgx_copy_number(S) if cn_rows: w("## PGx copy number") w("---") for g, v in cn_rows: w(f" {g:<8} {v}") w("") at("cyrius") calls = s["cyp2d6"]["calls"] verdict = cyp2d6_verdict(s["cyp2d6"]) if any(calls.values()) or verdict: w("## CYP2D6 across callers") w("---") if any(k in (ns.get("sections") or []) for k in ("pypgx", "cyrius")): # the consensus change is filed under pypgx w(f" [New since {ns.get('previous_utc') or 'the previous run'}]") for k, v in calls.items(): w(f" {CYP2D6_LABELS.get(k, k):<26} {v or 'not run'}") agree = s["cyp2d6"]["agree"] w(" pypgx and Cyrius agree: " + ("yes" if agree else "NO, review before acting on CYP2D6" if agree is False else "fewer than two usable calls")) if verdict: w(f" Step 36: {verdict}") if s["cyp2d6"].get("probable"): w(f" {s['cyp2d6']['probable']['label'].capitalize()}: {probable_text(s['cyp2d6']['probable'])}") w(f" {PGX_CALLERS_NOTE}") w("") if head("paralogs", "Paralog Genes (Paraphase, PacBio HiFi)"): for line in paralog_lines(S["paralogs"]["data"]): w(f" {line}") w(f" {PARALOG_NOTE}") w("") if head("parascopy", "SMN1/SMN2 Copy Number (Parascopy, short reads)"): for line in parascopy_lines(S["parascopy"]["data"]): w(f" {line}") for line in parascopy_locus_lines(S["parascopy"]["data"]): w(f" {line}") for line in cn_interval_lines(S["parascopy"]["data"].get("cn_intervals")): w(f" {line}") w(f" {PARASCOPY_NOTE}") w("") at("paralogs") unchecked = paralogs_unchecked(S) if unchecked: w("## Paralog Copy Number") w("---") w(f" {unchecked}") w("") if head("hla", "HLA Typing (T1K)"): for l in S["hla"]["data"]["loci"]: w(f" {l['gene']:<8} {hla_text(l)}") for line in hla_derived_lines(S["hla"]["data"].get("derived")): w(f" {line}") if S["hla"]["data"].get("derived"): w(f" {HLA_DERIVED_NOTE}") w(f" HLA database: {s['databases']['hla_database'] or 'unknown'}") w(f" {HLA_NOTE}") ot = S["hla"]["data"].get("optitype") if ot is not None: w(" OptiType check (HLA_QC=true, two fields):") for g, line in hla_optitype_lines(ot): w(f" {g:<8} {line}" if g else f" {line}") kir = S["hla"]["data"].get("kir") if kir is not None: w(" KIR genes (T1K, KIR=true):") for g, line in kir_lines(kir): w(f" {g:<8} {line}" if g else f" {line}") w(f" {KIR_NOTE}") w("") if head("locityper", "Locityper Second Opinion at Hard Loci (step 53)"): for line in locityper_lines(S["locityper"]["data"]): w(f" {line}") w(f" {LOCITYPER_NOTE}") w("") if head("prs", "Polygenic Risk Scores"): d = S["prs"]["data"] for r in d["scores"]: pct = prs_percentile(r) pct = f" {pct}" if r.get("sex_check") == PRS_NOT_APPLICABLE else (f" percentile {pct}" if pct else "") e = prs_effect(r) eff = "" if not e else (f" effect {e}" if r.get("effect") else f" {e}") w(f" {r['condition']:<35} {r['score']} ({r['matched']}/{r['total']} variants matched) {r['pgs_id']}{pct}{eff}") w(" " + prs_note(d)) w("") if head("ancestry_fine", "Fine-Grained Ancestry (ADMIXTURE, RFMix)"): d = S["ancestry_fine"]["data"] for level, title in ANCESTRY_FINE_LEVELS: rows = ancestry_fine_rows(d, level) if rows: w(f" {title} (fraction, bootstrap range):") for r in rows: w(f" {r['group']:<50} {share(r['fraction']):>5}{ancestry_fine_spread(r)}") if ancestry_fine_left_out(d): w(f" {ancestry_fine_left_out(d)}") w((" Chromosome painting, share of the painted genome: " if d.get("painting") else " Chromosome painting: ") + ancestry_fine_painted(d)) w(f" {ANCESTRY_FINE_NOTE}") w("") sv_note = [f" {SV_CALLERS_NOTE}"] # printed once, under the first structural caller with results if head("manta", "Structural Variants (Manta)"): d = S["manta"]["data"] w(f" Total SVs: {d['total']} PASS: {d['pass']}") while sv_note: w(sv_note.pop()) w("") if head("delly", "Structural Variants (Delly)"): d = S["delly"]["data"] w(f" Total SVs: {d['total']} PASS: {d['pass']}") while sv_note: w(sv_note.pop()) w("") if head("cnvpytor", "Copy Number Variants (CNVpytor)"): d = S["cnvpytor"]["data"] w(f" Total CNVs: {d['total']} ({d['deletions']} deletions, {d['duplications']} duplications)") w(f" Significant (e-val < 0.01): {d['significant']}") while sv_note: w(sv_note.pop()) filt = cnvpytor_filtered_text(d) if filt: w(f" Significant after filters: {filt}") w(f" {CNVPYTOR_NOTE}") w("") if head("sv_consensus", "SV Consensus Merge"): w(f" Consensus SVs (2+ callers): {S['sv_consensus']['data']['consensus']}") w("") if head("annotsv", "Structural Variants, Class 4 and 5 (AnnotSV)"): d = S["annotsv"]["data"] for line in annotsv_lines(d): w(f" {line}") for x in d["rows"]: w(f" {x['type']:<4} {x['sv']} class {x['acmg_class']} {annotsv_genes_text(x)} " f"support: {annotsv_support_text(x)}") for f in annotsv_flags(x): w(f" {f}") if d.get("downgraded"): w(" Moved to class 3 by step 05's rules (from AnnotSV's class, with the reason):") for x in d["downgraded"]: w(f" {annotsv_moved_text(x)}") if d["count"] or d.get("downgraded"): w(f" {ANNOTSV_NOTE}") w("") if head("expansions", "Repeat Expansions (ExpansionHunter)"): d = S["expansions"]["data"] w(f" Loci in output: {d['records']}") if d.get("stranger_outdated"): w(" Stranger's result is older than ExpansionHunter's: rerun step 9b. No locus is marked as normal or expanded.") elif not d.get("stranger"): w(" Stranger (step 9b) did not run: no locus is marked as normal or expanded.") elif d.get("flagged"): w(f" Outside the normal range (Stranger): {len(d['flagged'])}") by = {x["locus"]: x for x in d.get("loci") or []} for l in d["flagged"]: w(f" {l['locus']:<8} {str_count(by.get(l['locus'], l))} {l['status']}") if l.get("rfc1_motif"): w(f" {rfc1_text(l['rfc1_motif'])}") if l.get("motif"): w(f" {motif_text(l['locus'], l['motif'])}") else: w(" Outside the normal range (Stranger): none") if d.get("not_graded"): w(f" Not graded (no thresholds in the catalog): {len(d['not_graded'])} (" + "; ".join(f"{k}: {v}" for k, v in d["not_graded"].items()) + ")") w(f" {NOT_GRADED_NOTE}") for r in d.get("readings") or []: w(f" {repeat_reading_head(r)}") w(f" {r['reading']} ({r['source']})") if d.get("stranger") and d.get("no_status"): w(f" Loci without a Stranger status (not in its catalog): {d['no_status']}") if d.get("unsized"): w(f" Not sized from short reads, so not counted as normal: {len(d['unsized'])} ({', '.join(d['unsized'])})") if d.get("intermediate"): w(f" In an intermediate range (bin/str_intermediate_ranges.tsv): {', '.join(d['intermediate'])}") rows = str_rows(d) if rows: w(" Every locus (key loci first): repeat count, Stranger status, notes") for locus, count, status, notes in rows: w(f" {locus:<8} {count:<10} {status or '-'}" + (f" {notes}" if notes else "")) if any(l.get("rfc1_motif") for l in d.get("flagged") or []): w(f" {RFC1_NOTE}") w(f" {EH_NOTE}") w("") if head("telomere", "Telomere content (relative, TelomereHunter)"): w(f" Telomere content: {S['telomere']['data']['tel_content']} {TELOMERE_UNIT}") for line in telomere_lines(S["telomere"]["data"]): w(f" {line}") w(f" {TELOMERE_NOTE}") w("") if head("roh", "Runs of Homozygosity"): d = S["roh"]["data"] w(f" Segments: {d['segments']} Total: {d['total_mb']} MB Largest: {d['largest_mb']} MB") w(f" Autosomal ROH > 5MB: {len(d['autosomal_over_5mb'])}") for r in d["autosomal_over_5mb"]: w(f" {roh_region(r)}") for line in roh_lines(d): w(f" {line}") w("") if head("haplogroup", "Mitochondrial Haplogroup"): d = S["haplogroup"]["data"] w(f" Haplogroup: {d['haplogroup']}") w(f" Contamination (haplocheck): {contamination_text(d)}") for line in explore_lines(d): w(f" {line}") w("") if head("y_haplogroup", "Y-Chromosome Haplogroup (Yleaf)"): d = S["y_haplogroup"]["data"] w(f" Haplogroup: {d['haplogroup']} ({d['valid_markers']} markers, QC-score {d['qc_score']})") for line in explore_lines(d): w(f" {line}") w("") if head("y_tree", "Y Placement on the Current Public Tree"): d = S["y_tree"]["data"] w(f" Branch: {d['haplogroup']} (level {d['level']}, {d['tree']})") w(f" Path SNPs: {d['path_derived']} derived, {d['path_ancestral']} ancestral, " f"{d['path_no_call']} no call; {d['snps_called']} SNPs called at depth {d['min_depth']} or more") for label, key in (("Ancestral inside the terminal branch", "ancestral_in_terminal"), ("Ancestral on the path, outvoted by the SNPs below it", "outvoted_ancestral")): if d.get(key, ".") not in (".", ""): w(f" {label}: {d[key]}") for x in d.get("path", []): w(f" {x['Level']:>3} {x['Branch']:<22} {x['Derived']:>3}D {x['Ancestral']:>3}A {x['No_call']:>4}N") w(f" {Y_TREE_NOTE}") w("") if head("y_str", "Y-STR Markers (HipSTR)"): d = S["y_str"]["data"] w(f" {ystr_counts(d)}") for x in d["markers"]: if x["count"]: w(f" {x['panel']:<6} {x['marker']:<13} {x['count']:<6} ({x['confidence']})") w(f" {YSTR_NOTE}") w("") if head("consumer_export", "Raw-Data Export (23andMe v5 layout)"): for line in consumer_export_lines(S["consumer_export"]["data"]): w(f" {line}") w("") if head("bloodtype", "Blood Groups (predicted from the genome)"): for x in S["bloodtype"]["data"]["systems"]: w(f" {x['system']:<9} {x['phenotype']:<34} {x['genotype']:<28} ({x['confidence']})") w(f" {BLOODTYPE_NOTE}") w("") if head("lpa", "Lp(a): LPA KIV-2 Repeat Count and Risk Variants"): for line in lpa_lines(S["lpa"]["data"]): w(f" {line}") w(f" {LPA_NOTE}") w("") if head("vntyper", "MUC1 VNTR Frameshifts (ADTKD-MUC1, VNtyper)"): for line in vntyper_lines(S["vntyper"]["data"]): w(f" {line}") w(f" {VNTYPER_NOTE}") w("") if head("chip", "Clonal Haematopoiesis (CHIP, step 49)"): sink.extend(f" {line}" for line in chip_lines(S["chip"]["data"], s["sample"])) w("") if head("mito", "Mitochondrial Variants (Mutect2)"): d = S["mito"]["data"] w(f" PASS variants: {d['pass']}") w(f" Heteroplasmic (AF 0.05 to 0.95, outside the D-loop poly-C tracts): {d['heteroplasmic']}") for line in mito_lines(d): w(f" {line}") if d.get("polyc_heteroplasmic"): w(f" {MITO_POLYC_NOTE}") w(f" {MITO_NOTE}") w("") if head("traits", "Traits Panel (step 42)"): sink.extend(traits_text(S["traits"]["data"], s["sample"])) w("") if head("archaic", "Archaic Ancestry (IBDmix, step 43)"): for line in archaic_lines(S["archaic"]["data"]): w(f" {line}") w(f" {ARCHAIC_NOTE}") if head("ancient", "Ancient Populations (AADR PCA, step 44)"): for line in ancient_lines(S["ancient"]["data"]): w(f" {line}") w(f" {ANCIENT_NOTE} Plot: ancient/{s['sample']}_ancient_pca.svg") w("") if head("viral", "Viral DNA in the Unmapped Reads (step 47)"): for line in viral_lines(S["viral"]["data"]): w(f" {line}") w("") if head("exomiser", "Symptom-Driven Ranking (Exomiser, step 48)"): sink.extend(exomiser_text(S["exomiser"]["data"], s["sample"])) w("") if head("mei", "Mobile Element Insertions (step 50)"): for line in mei_lines(S["mei"]["data"]): w(f" {line}") w("") if head("mosaic", "Mosaic Chromosomal Alterations (MoChA, step 51)"): for line in mosaic_mca_lines(S["mosaic"]["data"]): w(f" {line}") w("") if head("cpsr", "Cancer Predisposition Screening (CPSR)"): d = S["cpsr"]["data"] if d.get("html_report"): w(" HTML report in cpsr/ (open in a browser)") if d.get("classification"): w(f" Classification breakdown ({d['classification_column']}):") for k, v in d["classification"].items(): w(f" {k}: {v}") elif "classification_column" in d: w(" Classification table has no CLASSIFICATION column.") for line in cpsr_lines(d, s["databases"]): w(f" {line}") w(f" {CPSR_NOTE}") w("") if head("clinical", "Clinical Variant Filter"): d = S["clinical"]["data"] w(f" Clinical variants: {d['variants']}" + (f" in {d['genes']} genes" if "genes" in d else "")) if d.get("by_impact"): w(" By impact: " + ", ".join(f"{k} {v}" for k, v in sorted(d["by_impact"].items()))) if "frequency_unknown" in d: w(f" Frequency unknown (not counted as rare): {d['frequency_unknown']}") if "weak_calls" in d: w(f" Weak genotype calls (check the reads): {d['weak_calls']}") sf = d.get("acmg_sf") if sf and sf.get("unavailable"): w(f" {sf_apart_lines(sf)[0]}") elif sf: w(f" Secondary-findings genes ({sf['version']}, {sf.get('genes_on_list', '?')} genes): " f"{len(sf['clinvar_hits'])} ClinVar P/LP, {high_rare(sf)} rare HIGH impact" + high_apart(sf) + (f", {len(sf['structural'])} class 4/5 SV(s)" if sf.get("structural_checked") else "") + (f", {len(sf['not_reported'])} not reported by the gene's rule" if sf.get("not_reported") else "")) for g, v, z, ev in sf_rows(sf): w(f" {g:<8} {v} {z} {ev}") for line in sf_apart_lines(sf): w(f" {line}") w(f" {ACMG_NOTE}") w("") if head("slivar", "Variant Prioritization (slivar)"): d = S["slivar"]["data"] w(f" Prioritized variants: {d['prioritized']}") if "frequency_unknown" in d: w(f" Frequency unknown (prioritized, not counted as rare): {d['frequency_unknown']}") if "compound_het_variants" in d: w(f" Compound het candidates: {d['compound_het_variants']} variants across {d['compound_het_genes']} genes") if "compound_het_phase" in d: for line in comphet_phase_text(d): w(line) elif "compound_het_variants" in d: w(" (Candidates only: unphased single-sample data. See docs/31-slivar.md)") w("") at("end") w("## Steps Not Run") w("---") if s["not_run"]: for t in s["not_run"]: w(f" - {t}") else: w(" All major steps completed.") w("") w("## Not Assessed by This Pipeline") w("---") for t in s["not_assessed"]: w(f" - {t}") w("") m = s["manifest"] if m: commit = next((r[2] for r in m if r[0] == "run" and r[1] == "git_commit"), "unknown") w(f"Run manifest: run_manifest.tsv (pipeline commit {commit}, " f"{sum(1 for r in m if r[0] == 'image')} images)") w("=" * 80) w(" DISCLAIMER: This is NOT a clinical report. Discuss findings with a") w(" qualified healthcare professional before making medical decisions.") w("=" * 80) lines = parts["top"] for n, (_, title, question, secs) in enumerate(CHAPTERS, 1): chapter = [x for sid, _, _ in secs for x in parts.get(sid, [])] if chapter: lines += ["#" * 80, f"# {n}. {title.upper()}: {question}", "#" * 80, ""] + chapter return "\n".join(lines + parts["end"]) + "\n" # --- html ------------------------------------------------------------------------ CSS = """ :root { --bg: #15171c; --card: #1e2128; --fg: #e3e5ea; --muted: #a3a9b4; --line: #2e333c; --head: #262a32; --accent: #8cbcf0; --hdr: linear-gradient(135deg, #12324d 0%, #1f5f8f 100%); --hdr-fg: #f2f6fa; --green-bg: #1d3b2a; --green-fg: #8ee0ae; --yellow-bg: #3f3618; --yellow-fg: #f2d77c; --red-bg: #4a2424; --red-fg: #f5a9a2; --gray-bg: #2d3139; --gray-fg: #b6bbc4; --state-bg: #1f3550; --state-fg: #a9cdf5; --stale-bg: #3c2e16; --stale-fg: #f4ca8c; --caveat-bg: #232a35; --disc-bg: #3a3214; --disc-line: #a8861c; color-scheme: dark; } * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--fg); line-height: 1.6; } a { color: var(--accent); } .layout { display: grid; grid-template-columns: 250px minmax(0, 1fr); gap: 24px; max-width: 1400px; margin: 0 auto; padding: 20px; } .toc { position: sticky; top: 0; align-self: start; max-height: 100vh; overflow-y: auto; padding: 8px 0; font-size: 13px; } .toc .toc-title { font-size: 15px; color: var(--accent); margin-bottom: 8px; } .toc ol { list-style: none; } .toc > ol > li { margin-bottom: 10px; } .toc > ol > li > a { font-weight: 600; } .toc ol ol { margin: 2px 0 0 4px; } .toc a { color: var(--fg); text-decoration: none; } .toc a:hover { color: var(--accent); } .dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; margin-right: 6px; } .dot-ok { background: #5b9ee6; } .dot-stale, .dot-incomplete { background: #e0b94a; } .dot-failed, .dot-part { background: #e2685d; } .dot-missing { background: #6b717c; } .header { background: var(--hdr); color: var(--hdr-fg); padding: 26px 30px; border-radius: 12px; margin-bottom: 16px; } .header h1 { font-size: 28px; margin-bottom: 8px; } .header .meta { opacity: 0.9; font-size: 14px; } .print-hint { font-size: 13px; color: var(--muted); margin-bottom: 20px; } .chapter { margin-bottom: 32px; } .chapter-title { font-size: 22px; color: var(--accent); } .question { color: var(--muted); margin-bottom: 14px; } .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 20px; } .sec { display: flex; flex-direction: column; gap: 20px; scroll-margin-top: 12px; } .sec:target .card { outline: 2px solid var(--accent); } .card { background: var(--card); border-radius: 10px; padding: 24px; box-shadow: 0 2px 8px rgba(0,0,0,0.3); } .card h2 { font-size: 18px; color: var(--accent); margin-bottom: 8px; padding-bottom: 8px; border-bottom: 2px solid var(--line); } .card h3 { font-size: 15px; margin: 12px 0 6px; } .sec-meta { font-size: 13px; color: var(--muted); margin-bottom: 8px; } .sec-meta .anchor { color: var(--muted); } .caveat { font-size: 13px; background: var(--caveat-bg); border-left: 3px solid var(--accent); padding: 6px 10px; margin-bottom: 10px; border-radius: 4px; } .note { font-size: 13px; color: var(--muted); margin-top: 8px; } .files { font-size: 13px; color: var(--muted); } .offsite-note { font-size: 12px; color: var(--muted); font-weight: normal; } .stat { display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid var(--line); gap: 12px; } .stat:last-child { border-bottom: none; } .stat .label { color: var(--muted); } .stat .value { font-weight: 600; text-align: right; } .badge { display: inline-block; padding: 2px 10px; border-radius: 12px; font-size: 13px; font-weight: 600; } .badge-green { background: var(--green-bg); color: var(--green-fg); } .badge-yellow { background: var(--yellow-bg); color: var(--yellow-fg); } .badge-red { background: var(--red-bg); color: var(--red-fg); } .badge-gray { background: var(--gray-bg); color: var(--gray-fg); } .badge-state { background: var(--state-bg); color: var(--state-fg); } .stale { background: var(--stale-bg); color: var(--stale-fg); border-radius: 6px; padding: 6px 10px; font-size: 13px; margin-bottom: 10px; } table { width: 100%; border-collapse: collapse; font-size: 14px; } th, td { padding: 8px 12px; text-align: left; border-bottom: 1px solid var(--line); } th { background: var(--head); font-weight: 600; color: var(--muted); } .full-width { grid-column: 1 / -1; } figure.chart { margin: 4px 0 12px; } figure.chart svg { display: block; max-width: 760px; } figure.chart a:focus, figure.chart a:hover { opacity: 0.8; } ul.plain { margin-left: 18px; } .disclaimer { background: var(--disc-bg); border: 1px solid var(--disc-line); border-radius: 8px; padding: 16px; margin-top: 24px; font-size: 14px; } .footer { text-align: center; color: var(--muted); font-size: 13px; margin-top: 24px; padding: 16px; } .footer table { font-size: 12px; color: var(--muted); margin-top: 8px; } @media (max-width: 900px) { .layout { display: block; } .toc { position: static; max-height: none; } } @media (max-width: 700px) { .grid { grid-template-columns: 1fr; } } /* Print is light. With a section or a chapter in the address (#id, from the contents), only it prints, with the header, the list of what is not assessed (.always) and the disclaimer. A browser without :has() prints everything. */ @media print { :root { --bg: #fff; --card: #fff; --fg: #111; --muted: #444; --line: #ccc; --head: #f0f0f0; --accent: #1a5276; --hdr: #fff; --hdr-fg: #111; --green-bg: #d5f5e3; --green-fg: #196f3d; --yellow-bg: #fef9e7; --yellow-fg: #7d6608; --red-bg: #fadbd8; --red-fg: #922b21; --gray-bg: #eee; --gray-fg: #555; --state-bg: #e3eefa; --state-fg: #1a4a7a; --stale-bg: #fdebd0; --stale-fg: #7e5109; --caveat-bg: #f4f6f8; --disc-bg: #fff3cd; --disc-line: #c9a227; color-scheme: light; } .toc, .print-hint, .sec-meta .anchor { display: none; } .layout { display: block; padding: 0; max-width: none; } .header { border: 1px solid #999; padding: 12px 16px; } .card { box-shadow: none; border: 1px solid #ccc; break-inside: avoid; } .sec:target .card { outline: none; } .grid { display: block; } .sec { margin-bottom: 16px; } body:has(main :target) .chapter:not(:target):not(:has(:target)):not(:has(.always)) { display: none; } body:has(.sec:target) .sec:not(:target):not(.always) { display: none; } body:has(.chapter:target) .chapter:not(:target) .sec:not(.always) { display: none; } body:has(main :target) .chapter:not(:target):not(:has(:target)) > .chapter-title, body:has(main :target) .chapter:not(:target):not(:has(:target)) > .question { display: none; } } """ STR_SIZING_TEXT = { "flanking_only": "size not determined (flanking reads only)", "in_repeat": "longer than a read (in-repeat reads only): shown as at least the interval's lower end", "low_confidence": "low confidence (fewer than 2 spanning reads, or the interval reaches the disease range)", "no_call": "no call", } RFC1_NOTE = ("RFC1: Stranger's catalog sizes the degenerate AARRG unit and flags a low count, so the motif " "decides. The motif count reads the reads at the locus; it cannot size a long expansion.") def str_count(l): """The repeat count of a locus: an in-repeat allele as >= the lower end of its interval, or 'not sized' without one.""" counts = l["repeat_count"].split("/") sizing = (l.get("allele_sizing") or "").split("/") cis = (l.get("ci") or "").split("/") out = [] for i, c in enumerate(counts): z = sizing[i] if i < len(sizing) else "" ci = cis[i] if len(cis) == len(counts) else (cis[0] if len(cis) == 1 else "") lo = ci.split("-")[0] if ci else "" if z == "in_repeat": c = f">={lo}" if lo.isdigit() else "not sized" out.append(c) return "/".join(out) def str_status(l): """Stranger's status, never 'normal' for a locus that was not sized.""" st = l.get("status") or "" if not st and l.get("not_graded"): return "not graded" if st == "normal" and l.get("sizing") not in ("sized", "unknown"): return "not sized" return st def str_notes(l): """What the report says beside a locus: sizing, the catalog's normal maximum, an intermediate range.""" out = [] if l.get("sizing") in STR_SIZING_TEXT: out.append(STR_SIZING_TEXT[l["sizing"]] + (f", interval {l['ci']}" if l.get("ci") not in (None, "", ".") else "")) if l.get("normal_max"): out.append(f"normal max {l['normal_max']}") if l.get("zone"): out.append(f"{l['zone']}: {l['zone_label']}; {l['zone_citation']}") if l.get("not_graded"): out.append(f"no thresholds in the catalog ({l['not_graded']})") if l.get("motif"): out.append(motif_text(l["locus"], l["motif"])) return "; ".join(out) def str_rows(d): """(locus, count, status, notes) for every locus, key loci first; a key locus missing from the output says so.""" rows = [(l["locus"], str_count(l), str_status(l), str_notes(l)) for l in d.get("loci") or []] have = {r[0] for r in rows} missing = [(k["locus"], "not in output", "", "") for k in d.get("key_loci") or [] if k["locus"] not in have] return missing + rows def rfc1_text(m): return motif_text("RFC1", m) def motif_text(locus, m): """Step 9b's motif count of a flagged locus (bin/rfc1_motif.py).""" return f"{locus} motif count: {m.get('verdict', '.')}: {m.get('note', '')}" def repeat_reading_head(r): """The first line of one reading of the repeats STRchive leaves out (CFTR, UGT1A1, 5-HTTLPR).""" what = r["genotype"] if r["status"] == "read" else r["status"].replace("_", " ") return f"{r['locus']} {r['repeat']}: {what}" NOT_GRADED_NOTE = ("Not graded: the repeat catalog gives these loci no thresholds (for MUC1, CEL, TYMS and PLIN4 " "the reference repeat is longer than 300 bases, so no short read spans it), so Stranger gives them no " "status. " "Not graded is not normal (docs/09-str-expansions.md).") PARALOG_NOTE = ("Paraphase reads PacBio HiFi reads only. A 'no call' means it saw one haplotype and the depth " "did not settle one copy or two. A research estimate, not a diagnostic test: confirm a result " "(for example an HBA deletion or one SMN1 copy) with a clinical laboratory.") def smn1_text(m): """SMN1 from Paraphase beside Parascopy (step 35), with the verdict.""" pc = m.get("parascopy") if pc is None: return None pp = m.get("paraphase") verdict = {"agree": "the two agree", "disagree": "they DISAGREE: check both before using either"}.get( m.get("agree"), "no comparison: one of them has no call") return f"Paraphase {pp if pp is not None else 'no call'}, Parascopy {pc['text']}: {verdict}" def paralog_lines(d): """Lines of the text report's paralog section.""" out = [f"{g['gene']}: {g['copy_number']} ({g['status']})" + ("" if g["detail"] in ("", ".") else f"; {g['detail']}") for g in d.get("genes", [])] smn = smn1_text(d.get("smn1") or {}) if smn: out.append(f"SMN1 by both tools: {smn}") if d.get("other_regions"): out.append(f"Other Paraphase regions: {d['other_regions']} ({d['other_regions_called']} with a call)") out.append(f"Variants on phased haplotypes: {sum(d.get('variants', {}).values())}") return out PARASCOPY_NOTE = ("Parascopy reads short reads at SMN1 and SMN2 and at the other loci of its catalog. A quality " "under 20 or a filter other than PASS leaves a copy unresolved. HBA1 and HBA2, CYP21A2 and the " "gene-dosage loci have no Parascopy model: step 35 counts them from read depth against flanking " "sequence (CYP21A2 also from six sites where it differs from its pseudogene CYP21A1P), which " "cannot say which chromosome lost or gained a copy. The copy-number intervals (ClinGen's " "recurrent CNV regions, carrier deletion alleles, the AZF regions) are read from depth too. " "A research estimate, not a diagnostic test: confirm a result with a clinical laboratory (MLPA " "or qPCR; gap-PCR for alpha-thalassaemia).") def parascopy_lines(d): """Step 35's lines, the same in both reports.""" smn1, smn2 = d.get("smn1") or {}, d.get("smn2") or {} return [f"SMN1 copies: {smn1.get('text', '.')}", f"SMN2 copies: {smn2.get('text', '.')}", f"SMN1 and SMN2 together (agCN) at exon 7: {d.get('agcn', '.')} (quality {d.get('agcn_qual', '.')}, " f"filter {d.get('agcn_filter', '.')})", f"Reading: {d.get('reading', '.')}"] + ([hba_line(d["hba"])] if d.get("hba") else []) \ + [cyp21a2_line(d.get("cyp21a2"))] + dosage_lines(d.get("dosage")) def cyp21a2_line(c): """Step 35's CYP21A2 call from depth and PSV sites, one line; not assessed only when the table says so or is not there.""" label = "CYP21A2 (RCCX module, from depth and six PSV sites)" if not c: return f"{label}: not assessed (step 35's _cyp21a2_psv.tsv is not in this run's output)" if c.get("status") != "called": why = c.get("message") or c.get("reason") or "." return f"{label}: not assessed ({why.removeprefix('not assessed: ')})" value = (f"{c.get('cyp21a2_copies', '.')} CYP21A2 copies, module total {c.get('module_total', '.')} of " f"{c.get('expected_total', '.')}, finding {c.get('finding', '.')}") if c.get("conversion_sites", ".") != ".": value += f" at {c['conversion_sites']}" if c.get("reading", ".") != ".": value += f". Reading: {c['reading']}" return f"{label}: {value}" DOSAGE_NAMES = {"HP": "HP (haptoglobin)", "LCE3BC": "LCE3B/LCE3C", "CCL3L1": "CCL3L1/CCL3L3"} def dosage_lines(rows): """Step 35's gene-dosage loci (HP, LCE3BC, CCL3L1), one line each.""" if rows is None: return ["Gene-dosage loci (HP, LCE3B/LCE3C, CCL3L1): not assessed (step 35's _cn_dosage.tsv is not " "in this run's output)"] if not rows: return ["Gene-dosage loci (HP, LCE3B/LCE3C, CCL3L1): not assessed (step 35's dosage table has no row)"] out = [] for r in rows: label = f"{DOSAGE_NAMES.get(r['locus'], r['locus'])} copies (from depth)" if r["status"] == "called": value = f"{r['copies']} (estimate {r['estimate']})" if r["reading"] != ".": value += f". Reading: {r['reading']}" else: value = f"{r['status']} ({r['reason']})" out.append(f"{label}: {value}") return out CN_INTERVALS_LABEL = "Copy-number intervals (ClinGen recurrent regions, carrier deletions, AZF; from depth)" def cn_interval_summary(iv): """The interval table in one line: rows by status and how many changed.""" if iv is None: return f"{CN_INTERVALS_LABEL}: not assessed (step 35's _cn_intervals.tsv is not in this run's output)" counts = ", ".join(f"{n} {k}" for k, n in sorted((iv.get("by_status") or {}).items())) or "no row" n = len(iv.get("changes") or []) k = (iv.get("by_status") or {}).get("called", 0) # Rows that were not called are no negative result: with none called the # line says so instead of "no deletion or duplication". end = (f"{n} with a deletion or a duplication" if n else f"no deletion or duplication among the {k} called rows" if k else "none called") return f"{CN_INTERVALS_LABEL}: {iv.get('rows', 0)} rows ({counts}); {end}" def cn_interval_place(r): """chrom:start-end (1-based) of an interval row of the table (BED).""" b = r.get("start", ".") return f"{r.get('chrom', '.')}:{int(b) + 1 if str(b).isdigit() else b}-{r.get('end', '.')}" def cn_interval_lines(iv): """The interval table for the text report: the summary, then one line per row with a deletion or a duplication.""" return [cn_interval_summary(iv)] + [ f" {r['change'].capitalize()}: {r['name']} ({r['locus']}, {cn_interval_place(r)}), " f"{r['copies']} of {r['expected']} copies" for r in (iv or {}).get("changes") or []] def cn_intervals_html(iv): """The interval table for the HTML card: the summary, then a table of the rows with a deletion or a duplication.""" label, value = cn_interval_summary(iv).split(": ", 1) out = [stat(label, E(value))] changes = (iv or {}).get("changes") or [] if changes: rows = "".join(f"{E(r['name'])}{E(r['locus'])}{E(cn_interval_place(r))}" f"{E(r['copies'])} of {E(r['expected'])}{E(r['change'])}" for r in changes) out.append(" " + rows + "
RegionRowPlaceCopiesChange
") return out PARASCOPY_LOCI_NOTE = ("The other loci of step 35's catalog (assets/paralog_loci.tsv): agCN is the copies of the " "gene and its paralogs together, read only with filter PASS and quality 20 or more; " "which copy gained or lost one is not said. Not assessed names the reason (most often: " "no read over the locus).") def parascopy_locus_lines(d): """One line per catalog locus other than SMN1, the same in both reports.""" out = [] for x in d.get("loci") or []: line = f"{x['genes'].replace(',', ', ')} (agCN): {x['text']}" if x.get("status") == "called" and x.get("reading", ".") != ".": line += f". Reading: {x['reading']}" out.append(line) return out def hba_line(h): """Step 35's HBA1/HBA2 count from depth, one line.""" if h.get("status") == "called": value = f"{h.get('alpha_globin_genes', '.')} ({h.get('message', '.')}; estimate {h.get('estimate', '.')})" else: value = h.get("message", "not assessed") return f"HBA1 and HBA2 together (alpha-globin genes, from depth): {value}" def parascopy_loci_html(d): """The other catalog loci as one table: genes, copies (agCN), reading.""" loci = d.get("loci") or [] if not loci: return [] rows = "".join(f"{E(x['genes'].replace(',', ', '))}{E(x['text'])}" f"{E(x['reading'] if x.get('status') == 'called' else '.')}" for x in loci) return [" " + rows + "
GenesCopies together (agCN)Reading
", small_note(PARASCOPY_LOCI_NOTE)] def paralogs_unchecked(S): """'Paralog copy number: not checked (...)' when neither step 35 nor step 35b left a result, so a report without them never reads as normal.""" states = {k: S.get(k, MISSING)["state"] for k in ("parascopy", "paralogs")} if any(v in ("ok", "stale") for v in states.values()): return None if all(v == "missing" for v in states.values()): why = "neither step 35 nor step 35b ran" else: words = {"missing": "not run", "failed": "failed", "unreadable": "unreadable"} why = ", ".join(f"step {st} {words.get(states[k], states[k])}" for k, st in (("parascopy", "35"), ("paralogs", "35b"))) return f"Paralog copy number: not checked ({why})" ACMG_NOTE = ("A list to review with a clinician, not a diagnosis. Each gene's ACMG SF v3.3 reporting rule " "(assets/acmg_sf.tsv) is applied: one variant in a dominant gene; two in a recessive gene such as " "MUTYH, BTD or ATP7B, even when their phase is unknown; HFE only as homozygous p.C282Y. A variant the " "rule does not report is listed apart with the reason. A rare HIGH-impact record is not a ClinVar " "classification.") CARRIER_NOTE = ("Carrier list: the ClinVar P/LP hits of this sample in the genes of assets/carrier_genes.tsv " "(autosomal recessive and X-linked conditions), one person, no partner needed. A carrier of one " "recessive change is usually healthy; the result matters for a child when a partner carries a " "change in the same gene (step 39). A hypomorph or pseudodeficiency allele is set aside.") def sf_rows(sf): """The secondary findings as (gene, variant, genotype, evidence) rows, the same in both reports: ClinVar hits, rare HIGH-impact records, then class 4 and 5 SVs.""" def extra(x): return "".join(f"; {v}" for v in (x.get("severity"), x.get("rule_note"), x.get("two_hit")) if v) rows = [(x["gene"], x["variant"], x["genotype"], "ClinVar " + x["significance"] + ("; low-confidence call: check the reads" if x.get("low_confidence") else "") + extra(x)) for x in sf["clinvar_hits"]] rows += [(x["gene"], x["variant"], x["genotype"], x["consequence"] + high_marks(x, "; ") + extra(x)) for x in sf["high_impact"]] def support(x): if x["support"] is None: return "caller support not known (no step 22 consensus)" return f"single caller ({x['caller']})" if x["support"] == 1 else f"{x['support']} callers" rows += [(x["gene"], x["variant"], ".", f"AnnotSV class {x['acmg_class']}, {support(x)}" + (f"; through {x['via']}" if x.get("via") else "") + extra(x)) for x in sf.get("structural", [])] return rows def sf_apart_lines(sf): """The variants in SF genes that the gene's rule does not report, or why no rule could be applied.""" if sf.get("unavailable"): return [f"Secondary findings: not assessed, {sf['unavailable']}"] return ([f"{x['gene']} {x['variant']} {x.get('genotype') or '.'} ({x['source']}): not reported, {x['reason']}" for x in sf.get("not_reported", [])] + ([sf["two_hit_note"]] if sf.get("two_hit_note") else [])) def carrier_lines(c): """The sample's own carrier list (no partner), the same in both reports.""" if c.get("unavailable"): return [f"Carrier list: not made, {c['unavailable']}"] lines = [f"Carrier list ({c['genes_on_list']} genes): {len(c['carriers'])} finding(s)" + (f", {len(c['set_aside'])} set aside" if c["set_aside"] else "")] def hemi(x): return f" ({x['hemizygous']})" if x.get("hemizygous") else "" for x in c["carriers"]: lines.append(f"{x['gene']} ({x['condition']}; {x['inheritance']}): {x['variant']} {x['genotype']}{hemi(x)}, " f"ClinVar {x['significance']}") for x in c["set_aside"]: lines.append(f"Set aside: {x['gene']} {x['variant']} {x['genotype']}{hemi(x)}: {x['name']} is a {x['kind']} " "allele, not a carrier finding on its own") return lines + two_hit_lines(c.get("two_hits")) def two_hit_lines(t): """The genes a called deletion and a ClinVar hit both reach (collect_summary.two_hits), and which deletion callers were read; none for a summary written before the rule.""" if not t: return [] lines = [] for x in t["genes"]: allele = f" ({x['allele']})" if x.get("allele") else "" lines.append(f"{x['verdict'].capitalize()}: {x['gene']} ({x['condition']}; AR), both copies may be hit: " f"{x['deletion']} and {x['variant']} {x['genotype']}{allele}; {x['why']}") lines.append("Two hits across callers (a deletion plus a variant on the other copy): " + (f"{len(t['genes'])} gene(s); " if t["genes"] else "none found; ") + "deletions read from " + ("; ".join(t["deletions_read"]) or "no caller") + (f"; not read: {'; '.join(t['deletions_not_read'])}" if t["deletions_not_read"] else "")) return lines def contamination_text(d): if "contamination_status" not in d: return "not checked (needs step 20's Mutect2 chrM calls)" s = d["contamination_status"] word = {"YES": "YES, two mtDNA haplogroups in the reads (another person's DNA?)", "NO": "no", "ND": "not determined"}.get(s, s) return f"{word} (level {d.get('contamination_level', '.')})" Y_TREE_NOTE = ("A second placement, on a public tree release newer than the one Yleaf carries, walked from the " "reads by bin/y_tree_place.py. The two can differ in depth and in name: branches get renamed and " "split between releases, and the position tables differ. A branch is taken when it has more " "derived than ancestral SNPs, and an ancestral call above it blocks the branches below unless the " "SNPs below outvote that one site. Every level is in y_haplogroup/_y_tree_path.tsv; " "docs/37-y-haplogroup.md says how the walk works.") def y_tree_body(d): """The Y tree card: the branch, the path counts, then one row per level.""" rows = "".join(f"{E(x['Level'])}{E(x['Branch'])}{E(x['Derived'])}" f"{E(x['Ancestral'])}{E(x['No_call'])}" f"{E(x['Ancestral_SNPs'])}" for x in d.get("path", [])) out = [stat("Branch", E(d.get("haplogroup", "."))), stat("Level", E(str(d.get("level", ".")))), stat("Tree", E(str(d.get("tree", "."))))] out.append(f"

Path SNPs: {E(str(d.get('path_derived', '.')))} derived, " f"{E(str(d.get('path_ancestral', '.')))} ancestral, {E(str(d.get('path_no_call', '.')))} no call; " f"{E(str(d.get('snps_called', '.')))} SNPs called at depth {E(str(d.get('min_depth', '.')))} " "or more

") for label, key in (("Ancestral inside the terminal branch", "ancestral_in_terminal"), ("Ancestral on the path, outvoted by the SNPs below it", "outvoted_ancestral")): if d.get(key, ".") not in (".", ""): out.append(f"

{label}: {E(str(d[key]))}

") if rows: out.append(" " "" + rows + "
LevelBranchDerivedAncestralNo callAncestral SNPs
") return out + explore_html(d) + [small_note(Y_TREE_NOTE)] YSTR_NOTE = ("Repeat counts read from the genome with HipSTR, in FamilyTreeDNA's Y-111 order. A count can " "differ from FamilyTreeDNA's by a fixed number of repeats at some markers, as labs count some repeat " "blocks differently: compare with a known result before trusting a difference. Multi-copy markers and " "repeats longer than the reads are not called. Every marker, with its reads and notes, is in " "y_str/_y_str.tsv; y_str/_y_str.csv is the same list for a spreadsheet.") def ystr_counts(d): return (f"Markers called: {d['high']} high and {d['low']} low confidence of {len(d['markers'])}; " f"{d['no_call']} no call, {d['not_callable']} not callable from short reads") def ystr_body(d): """The Y-STR card: the counts, then every called marker in FamilyTreeDNA's order.""" rows = "".join(f"{E(x['panel'])}{E(x['marker'])}{E(x['count'])}" f"{E(x['confidence'])}" for x in d.get("markers", []) if x["count"]) return [f"

{E(ystr_counts(d))}

", " " + rows + "
PanelMarkerRepeatsConfidence
", small_note(YSTR_NOTE)] BLOODTYPE_NOTE = ("Predicted from the DNA at the variants that define each antigen, not typed from blood. " "RhD comes from the read depth over RHD; weak and partial D are not assessed. " "The evidence for each site is in bloodtype/_bloodtype_evidence.tsv.") ARCHAIC_NOTE = ("An estimate from IBDmix against the Altai and Vindija Neanderthals and the Altai Denisovan: " "a segment counts when either copy carries it, and part of what any person gets is old shared " "ancestry, not gene flow (Africans get some too). Every segment: archaic/_archaic_segments.tsv; " "docs/43-archaic.md says where the numbers end.") def archaic_lines(d): """Step 43's lines, the same in both reports.""" mb = lambda bp: f"{bp / 1e6:.1f} Mb" lines = [f"Neanderthal: {d['neanderthal_percent']}% ({mb(d['neanderthal_bp'])} in {d['neanderthal_segments']} segments)", f"Denisovan: {d['denisovan_percent']}% ({mb(d['denisovan_bp'])} in {d['denisovan_segments']} segments)", f"Analysed: {mb(d['analysed_bp'])} of the autosomes; modern frequencies: 1000 Genomes {d.get('population', '.')}"] if d.get("longest"): lines.append("Longest segments:") lines += [f" {x}" for x in d["longest"]] return lines CHIP_NOTE = ("Clonal haematopoiesis is common with age and most people with it never get a blood cancer: " "a call here is not a diagnosis. A call is a change in a CHIP gene's published classes, found by " "Mutect2 without a matched normal; one at a VAF of 35% or more is left out as possibly inherited. " "docs/49-chip.md says how to read it.") def chip_lines(d, sample): """The CHIP section: the calls, the detection limit at this depth, the genes too shallow to read.""" out = [] for c in d.get("calls", []): out.append(f"{c['gene']} {c['protein_change']}: VAF {c['vaf']} ({c['alt_reads']} of {c['depth']} reads), {c['note']}") if not d.get("calls"): out.append("No CHIP call.") if d.get("median_limit") is not None: out.append(f"Detection limit: a clone of VAF about {d['median_limit'] * 100:.0f}% or more is found 8 times " f"in 10 at this depth (median {d['median_depth']:.0f}x over the genes' coding exons). CHIP starts " "at a VAF of 2%: smaller clones are likely missed, so no call does not rule one out.") else: out.append("No CHIP gene has the depth to find a clone: no result either way.") if d.get("not_covered"): out.append(f"Too shallow or not on the reference: {', '.join(d['not_covered'])}.") out.append(f"{d.get('other', 0)} other protein changes listed, not counted: chip/{sample}_chip.tsv.") out.append(CHIP_NOTE) return out def bloodtype_body(d): """The blood group card: one row per system, then what the prediction is.""" rows = "".join(f"{E(x['system'])}{E(x['phenotype'])}{E(x['genotype'])}" f"{E(x['confidence'])}" for x in d.get("systems", [])) return [stat("ABO", E(d.get("abo", "."))), stat("RhD", E(d.get("rhd", "."))), " " + rows + "
SystemPredicted phenotypeGenotypeConfidence
", small_note(BLOODTYPE_NOTE)] def lpa_lines(d): """Step 46's count with its interval, step 42's two LPA risk variants, the flag and the advice: the lines of the text section and the card.""" if d.get("status") == "estimated": out = [f"KIV-2 repeats (both chromosomes): {d['kiv2_copies']} (95% interval {d['ci95_low']} to " f"{d['ci95_high']}), {d['class']}"] else: out = [f"KIV-2 repeats: {d.get('status', '.')}"] out.append(f" {d.get('message', '.')}") for v in d.get("variants", []): n = v["risk_alleles"] out.append(f"{v['rsid']}: {v['genotype']} ({'not read' if n is None else str(n) + ' risk allele' + ('s' if n != 1 else '')})") if not d.get("variants"): out.append("rs10455872 and rs3798220: not read (step 42, the traits panel, did not run)") out.append(d.get("flag_text", ".")) out.append(d.get("advice", ".")) return out LOCITYPER_NOTE = ("A second opinion beside the primary caller, never the call itself. Locityper (Prodanov et al. 2025, " "Nat Genet, PMID 41107551) picks the two haplotypes of the HPRC pangenome panel that best explain the " "reads at each locus; it names haplotypes of panel people (.1 or .2), not alleles, so the " "two callers are shown side by side and not compared. Filter: the authors' HLA and KIR benchmark " "filter (no warning, weighted distance of 30 or less, fewer than 1000 or 20% unexplained reads). " "Every column: locityper/_locityper.tsv.") def locityper_text(x): """One locus of step 53: the two haplotypes with quality and filter, or why there is no call.""" if x["status"] != "called": return f"not called: {x['reason']}" why = f": {x['reason']}" if x["filter"] == "fail" and x["reason"] != "." else "" return (f"{x['haplotype_1']} + {x['haplotype_2']} (quality {x['quality']}, {x['unexplained_reads']} of " f"{x['total_reads']} reads unexplained, weighted distance {x['weighted_distance']}; filter {x['filter']}{why})") def locityper_lines(d): """Step 53's lines: per locus Locityper's call, then the primary caller's.""" out = [f"Loci called: {d.get('called', 0)} of {len(d.get('loci', []))}; passing the authors' filter: " f"{d.get('passed', 0)}"] for x in d.get("loci", []): out.append(f"{x['locus']:<9} Locityper: {locityper_text(x)}") out.append(f"{'':<9} primary: {x.get('primary', '.')}") return out def vntyper_lines(d): """Step 52's reading: the result, the call, the depth with its sensitivity, and the advice; the lines of the text section and the card.""" out = [f"Result: {d.get('status', '.')}", d.get("message", ".")] if d.get("variant", ".") != ".": out.append(f"Variant: {d['variant']} (Kestrel confidence {d.get('confidence', '.')}, " f"{d.get('alt_depth', '.')} k-mer paths for the variant)") out.append(f"VNtyper's coverage check: {d.get('coverage_qc', '.')}") out.append(d.get("sensitivity", ".")) out.append(d.get("advice", ".")) return out VIRAL_NOTE = ("From the reads that do not map to the human genome, realigned to a fixed set of human viral " "genomes. Not a test for an infection: most adults carry herpesviruses that stay in their cells, and " "reagents carry viral DNA too. HHV-6 integration follows Liu et al. 2020 (depth over the viral genome " "at 0.30 of the human depth or more). Every genome: viral/_viral.tsv.") def viral_lines(d): """Step 47's lines, the same in both reports: the HHV-6 call, then each genome with reads.""" lines = [f"HHV-6: {d.get('hhv6', '.')}"] for x in d.get("found", []): copies = "" if x["copies_per_cell"] == "." else f", {x['copies_per_cell']} copies per cell" lines.append(f"{x['virus']}: {x['call']} ({x['reads']} reads, {float(x['breadth']):.0%} of the genome{copies})") if not d.get("found"): lines.append(f"No read on any of the {d.get('genomes', 0)} viral genomes.") return lines + [VIRAL_NOTE] def viral_body(d): """The viral DNA card: the HHV-6 call, a row per genome with reads, the note.""" rows = "".join(f"{E(x['virus'])}{E(x['call'])}{E(x['reads'])}" f"{E(x['breadth'])}{E(x['relative_depth'])}{E(x['copies_per_cell'])}" for x in d.get("found", [])) table = (" " "" + rows + "
VirusCallReadsBreadthDepth / humanCopies per cell
") if rows else small_note("No read on any viral genome.") return [stat("HHV-6", E(d.get("hhv6", "."))), table, small_note(VIRAL_NOTE)] MEI_NOTE = ("Alu, L1 and SVA copies the genome carries and the reference does not, found and genotyped by " "MEGAnE (Kojima et al. 2023) from short read pairs. Most are common and harmless; the catalog rows are " "insertions known to cause disease. Not callable: too few reads in that window to tell. Not seen is " "not proof of absence: short reads find an SVA's edges, not its body. Every call: mei/_mei.tsv.") def mei_lines(d): """Step 50's lines, the same in both reports: the calls per element, then each catalog row.""" by = d.get("by_element") or {} counts = ", ".join(f"{k} {v}" for k, v in by.items()) or "none" lines = [f"Insertions called: {d.get('calls', 0)} ({counts})"] for x in d.get("sites", []): call = "" if x["call"] == "." else f", {x['call']}" lines.append(f"{x['gene']} {x['element']} ({x['condition']}; {x['inheritance']}): {x['status']}" f" (depth {x['mean_depth']}{call})") return lines + [MEI_NOTE] def mei_body(d): """The mobile element card: the calls per element, a row per catalog insertion, the note.""" by = d.get("by_element") or {} counts = ", ".join(f"{k} {v}" for k, v in by.items()) or "none" rows = "".join(f"{E(x['gene'])}{E(x['element'])}{E(x['condition'])}" f"{E(x['inheritance'])}{E(x['status'])}{E(x['mean_depth'])}" f"{E(x['call'])}" for x in d.get("sites", [])) table = (" " "" + rows + "
GeneElementConditionInheritanceStatusDepthCall
") return [stat("Insertions called", E(f"{d.get('calls', 0)} ({counts})")), table, small_note(MEI_NOTE)] MCA_NOTE = ("Large gains, losses and copy-neutral losses of heterozygosity (CN-LOH) carried by a share of the " "blood cells, from MoChA on the phased heterozygous sites of chr1 to chr22. In a UK Biobank study they " "became more common with age and went with a higher risk of a later blood cancer (Loh et al. 2018). " "That is a population-level association, not a diagnosis; an event is confirmed on a new blood sample. " "Below the floor nothing is reported, and an event above it can still be missed. " "Every MoChA call, with the reason it was or was not reported: mosaic/_mocha.tsv.") def mosaic_mca_lines(d): """Step 51's lines, the same in both reports: the floor, then each call or the reason none is shown.""" if d.get("status") != "assessed": return [f"Not assessed: {d.get('message', '.')}", MCA_NOTE] out = [f"Reported at a cell fraction of {d.get('floor', '.')} or more at {d.get('depth', '.')}x " f"(read-sampling floor {d.get('floor_read', '.')}, minimum {d.get('floor_min', '.')}; " f"{d.get('het_sites', '.')} heterozygous sites on {d.get('chromosomes', '.')})"] for x in d.get("calls", []): out.append(f"{x['type']} on {x['arms']}, {x['chrom']}:{x['start']}-{x['end']} ({x['length_mb']} Mb): " f"about {x['cell_fraction']} of the cells") if not d.get("calls"): out.append(f"No mosaic alteration reported ({d.get('calls_mocha', '0')} MoChA calls, none kept).") return out + [MCA_NOTE] def mosaic_mca_body(d): """The MoChA card: a row per reported call, or the reason there is none.""" if d.get("status") != "assessed": return [stat("Status", badge("Not assessed", "gray")), small_note(d.get("message", ".")), small_note(MCA_NOTE)] rows = "".join(f"{E(x['type'])}{E(x['arms'])}{E(x['chrom'])}:{E(x['start'])}-{E(x['end'])}" f"{E(x['length_mb'])}{E(x['cell_fraction'])}{viewer_td(x['chrom'], x['start'], x['end'])}" for x in d.get("calls", [])) table = (f" {VIEWER_TH}" + rows + "
TypeArmRegionMbCell fraction
\n" + VIEWER_NOTE) if rows else small_note("No mosaic alteration reported.") lines = mosaic_mca_lines(d) return [stat("Calls reported", E(d.get("calls_reported", "0"))), stat("Cell-fraction floor", E(d.get("floor", "."))), table, small_note(lines[0]), small_note(MCA_NOTE)] ROH_NOTE = ("Autosomes only: chrX and chrY are left out, and so is the part of a segment in a centromere or " "heterochromatin band (GRCh38 cytoband acen, gvar, stalk), where few markers map. No population allele " "frequencies were used (bcftools roh --AF-dflt 0.4): read the total and the short segments as rough; " "the long segments are the signal.") CNVPYTOR_NOTE = ("Filtered: e-value below 0.01, under half of the reads with mapping quality 0 (q0) and under half " "N bases (pN), no overlap with a centromere or heterochromatin band, and no chrY call when the " "declared sex is female.") MITO_POLYC_NOTE = ("Length heteroplasmy in the D-loop poly-C tracts is found in most people and is usually " "technical; it is listed here and not counted as heteroplasmy.") MITO_NOTE = ("ClinVar and gnomAD v3.1 (chrM sites) annotate the calls in step 20. MITOMAP (mitomap.org) has the " "curated disease status of mtDNA variants; it is a manual lookup, as it refuses scripted requests.") ROH_UPD_NOTE = ("Long runs concentrated on one chromosome, with few elsewhere, are the sign of isodisomy: both " "copies of that chromosome from one parent. They can also be chance in a child of related parents. " "Which parent gave both copies cannot be told without the parents' samples, and a heterodisomy (two " "different copies from one parent) leaves no runs at all. The parents' genotypes confirm a UPD. " "Where an imprinted region is listed, a methylation test of that region tests for its imprinting " "disorder; on its own it does not prove a UPD (docs/11-roh-analysis.md).") ROH_F_NOTE = "F_ROH is the share of the autosomes (outside the bands) in runs of 5 MB or more." ROH_BAND_NOTE = ("The band is the row of docs/11-roh-analysis.md's table it is nearest to: an average, and neighbouring " "rows overlap, so it is consistent with that relationship, not a proof of it.") def roh_lines(d): """Step 11's lines under the headline, the same in both reports.""" lines = [] if isinstance(d.get("f_roh"), (int, float)): band = d.get("relationship") or "no band (one chromosome holds most of the runs)" lines.append(f"F_ROH: {d['f_roh']:.4f} ({d.get('long_mb')} MB in runs of 5 MB or more); nearest: {band}") u = d.get("upd_flag") if u: lines.append(f"** {u['chrom']} carries {u['mb']} MB, more than 50% of the length in runs of 5 MB or more: " f"both copies may come from one parent (uniparental isodisomy) **") for r in u.get("imprinted", []): lines.append(f"Imprinted {r['region']}: from the mother: {r['maternal_upd']}; from the father: " f"{r['paternal_upd']} (PMID {r['pmid']})") if not u.get("imprinted"): lines.append(f"No listed imprinting-disorder region overlaps the flagged runs on {u['chrom']} " "(assets/imprinted_regions.tsv); " "a recessive variant in the run, if there is one, would be homozygous") lines.append(ROH_UPD_NOTE) if isinstance(d.get("f_roh"), (int, float)): lines.append(ROH_F_NOTE + (" " + ROH_BAND_NOTE if d.get("relationship") else "")) if d.get("masked_mb"): lines.append(f"Left out in centromere and heterochromatin bands: {d['masked_mb']} MB") if d.get("sex_chromosome_segments"): lines.append(f"Segments on chrX/chrY, not counted: {d['sex_chromosome_segments']}") return lines + [ROH_NOTE] KARYOTYPE_NOTE = ("Named from the copy number of chrX and chrY in the reads. A mixed sample or a sample swap can " "give the same numbers. A mosaic in about 30 to 70% of the cells gives numbers between whole ones " "and no name; one in more of the cells can round to a whole number and be named (a Y lost in 75% " "of the cells reads 45,X). Confirm with " "a karyotype or a chromosomal microarray (docs/33-sample-qc.md).") def karyotype_lines(S): """One line per source that names a sex-chromosome karyotype (indexcov, step 16; somalier, step 33), then the note; none when neither names one.""" out = [] sc, sq = S.get("sex_check", {}), S.get("sample_qc", {}) if sc.get("state") in ("ok", "stale") and sc["data"].get("karyotype"): q = sc["data"] out.append(f"Sex chromosomes: {q['karyotype']} (indexcov copy number chrX {q.get('cn_chrX')}, " f"chrY {q.get('cn_chrY')})") if sq.get("state") in ("ok", "stale") and sq["data"].get("karyotype"): q = sq["data"] out.append(f"Sex chromosomes: {q['karyotype']} (somalier depth over the autosomes chrX " f"{q.get('x_depth_ratio')}, chrY {q.get('y_depth_ratio')}; one copy reads 0.5)") return out + [KARYOTYPE_NOTE] if out else [] def roh_region(r): return f"{r['region']} {r['mb']}MB" + (f" ({r['masked_mb']} MB in a band left out)" if r.get("masked_mb") else "") def telomere_lines(d): """The read count under the telomere value, and the warning when it is too thin.""" if "intratelomeric_reads" not in d: return [f"Intratelomeric reads: not checked ({d['read_check']})"] if d.get("read_check") else [] n = f"{d['intratelomeric_reads']:,}" if "read_floor" not in d: return [f"Intratelomeric reads: {n}; {d.get('read_check', 'not checked')}"] lines = [f"Intratelomeric reads: {n} (floor {d['read_floor']:,} at {d['depth']}x)"] if d.get("low_reads"): lines.append("WARNING: too few telomeric reads for a stable estimate; do not compare this value.") return lines def cnvpytor_filtered_text(d): if "significant_filtered" not in d: return None dr = d.get("dropped") or {} parts = [f"{dr[k]} {label}" for k, label in (("q0", "q0 0.5 or more"), ("gap", "over N gaps (pN 0.5 or more)"), ("band", "over a centromere or heterochromatin band"), ("chry_female", "on chrY of a declared female")) if dr.get(k)] out = f"{d['significant_filtered']}" + (f" (left out: {', '.join(parts)})" if parts else "") if not d.get("declared_sex"): out += "; no declared sex, so chrY calls are kept" return out def mito_variant_text(v): def val(x): return "." if x in (None, "", ".") else x cv = val(v.get("clinvar_significance")) cv = "not in ClinVar" if cv == "." else f"ClinVar {cv} ({val(v.get('clinvar_review'))}; {val(v.get('clinvar_condition'))})" gn = ("not in gnomAD" if val(v.get("gnomad_af_hom")) == "." else f"gnomAD AF hom {v['gnomad_af_hom']}, het {val(v.get('gnomad_af_het'))}") return f"chrM:{v['pos']} {v['ref']}>{v['alt']} AF {val(v.get('af'))} {cv} {gn}" + (" poly-C tract" if v.get("polyc") else "") def mito_lines(d): """Step 20's lines under the counts, the same in both reports.""" lines = [] pc = d.get("polyc_heteroplasmic") or [] if "polyc_heteroplasmic" in d: lines.append(f"Length heteroplasmy in the D-loop poly-C tracts ({', '.join(d.get('polyc_tracts') or [])}; " f"common, usually technical): {len(pc)}") lines += [f" {x['variant']} AF {x['af']}" for x in pc] a = d.get("annotation") or {} if a.get("source"): lines.append(f"Annotation ({a['source']}): ClinVar {a.get('clinvar') or 'unknown'}; gnomAD {a.get('gnomad') or 'unknown'}") lines.append(f"ClinVar pathogenic or likely pathogenic: {a.get('clinvar_plp', 0)}") if a.get("variants"): lines.append("Heteroplasmic, or in ClinVar with a class other than benign:") lines += [f" {mito_variant_text(v)}" for v in a["variants"]] elif a.get("note"): lines.append(f"ClinVar and gnomAD: not annotated ({a['note']})") return lines + mito_extended_lines(d) MITO_DELETION_NOTE = ("A single large mtDNA deletion is often found in muscle and not in blood (except in Pearson " "syndrome), so a blood sample with none does not rule one out (docs/20-mtoolbox.md).") MITO_COPIES_NOTE = ("mtDNA copies per cell: twice the chrM depth over the autosomal depth, from the read counts of " "the BAM index, for a whole-genome BAM (an exome gives no such number). It depends on the tissue " "and the library, so it compares samples of one kind only.") def mito_confirmed_text(v): return (f"{v['hgvs']} ({v['gene']}) AF {v.get('af') or '.'} filter {v.get('filter') or '.'} {v['disease']}; " f"ClinVar {v['clinvar_id']}; PMID {v['pmids'].replace(';', ', ')}. {v['note']}") def mito_deletion_text(r): k = r.get("known") span = (f"m.{r['bkp5'] + 1}_{r['bkp3'] - 1}del ({r['length']} bp)" if r["bkp3"] > r["bkp5"] else f"m.{r['bkp5'] + 1} to m.{r['bkp3'] - 1} across the origin ({r.get('length')} bp)") out = f"{span} level {r['level_pct']}%" if k: out += f" {k['disease']}; ClinVar {k['clinvar_id']} ({k['hgvs']}); PMID {k['pmids'].replace(';', ', ')}" return out def mito_copies_text(c): if c.get("status") == "called": return (f"mtDNA copy number: {c['mtdna_copies']} per cell (chrM depth {c['depth_ratio']} times the " f"autosomal depth)") reason = {"low_autosomal_depth": "too few autosomal reads: a sliced BAM, a panel or a shallow genome", "no_chrM_reads": "no chrM reads in the BAM"}.get(c.get("reason"), c.get("reason") or "unknown") return f"mtDNA copy number: not assessed ({reason})" def mito_extended_lines(d): """Step 20's confirmed variants, large deletions and copy number, the same in both reports.""" lines = [] if "confirmed" in d: conf = d["confirmed"] lines.append(f"Confirmed disease variants (assets/mito_confirmed.tsv): {len(conf)}") lines += [f" {mito_confirmed_text(v)}" for v in conf] if d.get("confirmed_note"): lines.append(f"Confirmed disease variants: not checked ({d['confirmed_note']})") dl = d.get("deletions") if dl: named = sum(1 for r in dl["listed"] if r.get("known")) lines.append(f"Large deletions (eKLIPse): {dl['total']}, of them {named} named in assets/mito_confirmed.tsv; " f"listed: named ones and any at {dl['list_floor_pct']}% or more") lines += [f" {mito_deletion_text(r)}" for r in dl["listed"]] lines.append(MITO_DELETION_NOTE) elif d.get("deletions_note"): lines.append(f"Large deletions: not looked for ({d['deletions_note']})") if d.get("copies"): lines.append(mito_copies_text(d["copies"])) if d["copies"].get("status") == "called": lines.append(MITO_COPIES_NOTE) elif d.get("copies_note"): lines.append(f"mtDNA copy number: not counted ({d['copies_note']})") return lines # scripts/owngenome-view.sh serves the genome viewer here (OWNGENOME_VIEW_PORT's default); # the part after '#' is the locus it opens at. The live site's viewer plugin # (bin/owngenome_live_viewer.py) points this address and VIEWER_NOTE at its own viewer # in the report it serves. VIEWER_URL = "http://127.0.0.1:8765/" # Every findings table ends with a Viewer column: one link per row, to the row's locus. A column # of its own leaves every other cell's text as it was. VIEWER_TH = "Viewer" VIEWER_NOTE = ('

The Viewer column opens the reads at each row in the genome viewer ' "on this computer (start it first: scripts/owngenome-view.sh <sample>, docs/viewer.md).

") LOCUS_IN_TEXT = re.compile(r"([A-Za-z0-9_.]+):([0-9]+)(?:-([0-9]+))?(?![0-9])") def viewer_td(chrom, start, end=None): """The Viewer cell of a row: a link that opens chrom:start, or chrom:start-end, in the genome viewer; an empty cell without a position.""" if not chrom or not start: return "" where = f"{chrom}:{start}" + (f"-{end}" if end and str(end) != str(start) else "") return (f'
' f"{E(where)}") def viewer_td_of(text): """The Viewer cell of a row whose locus is written in text ("chr1:100 A>G", "DEL chr1:5-90", "chr1:50 A>G + chr1:90 C>T"): the span of every position on the first one's chromosome.""" found = LOCUS_IN_TEXT.findall(str(text or "")) if not found: return "" chrom = found[0][0] pos = [int(x) for c, a, b in found if c == chrom for x in (a, b) if x] return viewer_td(chrom, min(pos), max(pos)) EXPLORE_NOTE = ("Nothing is uploaded by this pipeline. The docs link lists the files each service reads, " "which steps 12 and 37 write when they run, and what an upload shares.") def explore_lines(d): """Where to explore a haplogroup further, the same in both reports: the links built from the branch name, then the note.""" lines = [f"{x['name']}: {x['url']}" for x in d.get("explore", [])] return lines + [EXPLORE_NOTE] if lines else [] # An address that leaves this computer: marked, so a reader knows before # opening it. The haplogroup links carry the haplogroup in the address. OFFSITE = "opens a website" OFFSITE_HAPLOGROUP = "opens a website; the address carries the haplogroup" def offsite_link(url, text, why=OFFSITE): return (f'{E(text)} ' f'({E(why)})') def explore_html(d): # Every explore address but the docs one carries the haplogroup, percent-encoded # and for Y cut at its "*", so it is told by where it goes, not by a substring. rows = [stat(x["name"], offsite_link(x["url"], x["url"], OFFSITE if x["url"].startswith(collect_summary.EXPLORE_DOCS) else OFFSITE_HAPLOGROUP)) for x in d.get("explore", [])] return rows + [small_note(EXPLORE_NOTE)] if rows else [] def stat(label, value): return f'
{E(str(label))}{value}
' def small_note(text): """A sentence under a card's numbers.""" return f'

{E(text)}

' def badge(text, colour): return f'{E(str(text))}' def done_badge(sec): """The Status badge of a section that ran: Complete, or Stale for a result from an earlier run.""" return badge("Stale", "yellow") if sec["state"] == "stale" else badge("Complete", "green") CONSUMER_NOTE = ("These files stay on this machine. Uploading one to a service shares your genotypes with it, " "and with the relatives it matches you to: docs/40-export-consumer.md says what to weigh first.") def consumer_export_lines(d): """Step 40's lines, the same in both reports.""" sites, called = d.get("sites", 0), d.get("called", 0) pct = f" ({100.0 * called / sites:.1f}%)" if sites else "" lines = [f"Sites with a genotype: {called} of {sites}{pct}; '--' at {d.get('no_call', 0)}", f"Homozygous reference from the gVCF's reference blocks: {d.get('from_reference_blocks', 0)}", f"Files: consumer_export/{d.get('file_23andme', '.')} and consumer_export/{d.get('file_ancestrydna', '.')}"] reasons = d.get("no_call_reasons") or {} if reasons: lines.append("'--' because: " + "; ".join(f"{k} {v}" for k, v in sorted(reasons.items(), key=lambda x: -x[1]))) return lines + [CONSUMER_NOTE] def card(sec, title, body, full=False): """A card for one section; a missing one shows 'Not run', a failed one 'Failed', a stale one its note.""" lines = [f'
', f"

{E(title)}

"] if sec is not None and sec["state"] in ("stale", "unreadable", "failed"): lines.append(f'
{E(stale_note(sec))}
') if sec is not None and sec["state"] in ("missing", "unreadable", "failed"): lines.append(stat("Status", {"missing": badge("Not run", "gray"), "failed": badge("Failed", "red")} .get(sec["state"], badge("Unreadable", "gray")))) else: lines += body lines.append("
") return lines def html_report(s, index=None): """The HTML report. INDEX is the search index (results_index.build) its closing appendix lists; without one it is built from the summary alone, which leaves out the step 23 and 31 tables (they need the sample folder).""" S = s["sections"] # Each card goes into its section's list; html_page() lays the lists out # in CHAPTERS order. parts = {} def a(key, lines): parts.setdefault(SECTION_OF[key], []).extend(lines) # QC cov, sexc = S["coverage"], S["sex_check"] md = cov["data"].get("mean_depth") inferred = sexc["data"].get("inferred_sex") declared = s["run"]["declared_sex"] sex_badge = E(inferred or "not available") if inferred and declared: sex_badge = badge(inferred, "green" if inferred == declared else "red") qc = [stat("Mean depth", f"{md:.1f}x" if isinstance(md, (int, float)) else "not available"), stat("Inferred sex (indexcov)", sex_badge), stat("Declared sex", E(declared or "not declared"))] rdc = S.get("read_count", MISSING) if rdc["state"] in ("ok", "stale"): qc.insert(1, stat("Reads kept by alignment", badge(read_count_text(rdc["data"]), "green" if rdc["data"].get("read_count_check") == "ok" else "red"))) sqc = S.get("sample_qc", MISSING) if sqc["state"] in ("ok", "stale"): q = sqc["data"] check = q.get("sex_check") qc.append(stat("Sex from the reads (somalier)", badge(q.get("inferred_sex", "unknown"), "green" if check == "ok" else "red" if check == "mismatch" else "gray"))) if check == "not_checked": qc.append(stat("Not checked", f'' f'{E(q.get("sex_check_reason", ""))}')) colour = {"ok": "green", "warn": "yellow"}.get(q.get("contamination"), "gray") qc.append(stat("Contamination (FREEMIX)", badge(freemix_text(q), colour))) if q.get("same_person_as"): qc.append(stat("The same person as", badge(q["same_person_as"], "red"))) else: qc.append(stat("Identity and contamination (step 33)", badge("Not run", "gray"))) kl = karyotype_lines(S) qc += [stat("Sex chromosomes", badge(x.split(": ", 1)[1], "red")) for x in kl[:-1]] + [small_note(x) for x in kl[-1:]] qc.append(small_note(COVERAGE_NOTE)) qc_note = [f'
{E(sec["title"] + ": " + stale_note(sec))}
' for sec in (cov, sexc, sqc, rdc) if stale_note(sec)] a("coverage", ['
', "

Quality Control

"] + qc_note + qc + ["
"]) ca = S.get("callability", MISSING) if ca["state"] != "missing": cd = ca["data"] ca_body = ([stat("Genes read", f"{cd['read']} of {cd['catalog_genes']}"), stat("Not read, no other caller", badge(len(cd["not_read"]), "red" if cd["not_read"] else "green"))] if ca["state"] in ("ok", "stale") else []) ca_body += [small_note(line) for line in (callability_lines(cd) if ca["state"] in ("ok", "stale") else [])] a("callability", card(ca, "Genes This Genome Could Not Read Reliably", ca_body + [small_note(CALLABILITY_NOTE)])) mo = S.get("mosaic_sex_loss", MISSING) q = mo["data"] label, colour = MOSAIC_CALL.get(q.get("call"), (q.get("call") or "?", "gray")) mo_body = [stat(q.get("chrom") or "chrY or chrX", badge(label, colour)), stat("Why", f'{E(q.get("reason") or "")}')] mo_body += [small_note(line) for line in mosaic_lines(q)] + [small_note(MOSAIC_NOTE)] a("mosaic_sex_loss", card(mo, "Mosaic Loss of Chromosome Y or X", mo_body)) v = S["variants"]["data"] a("variants", card(S["variants"], "Variant Calling", [stat("Total variants", v.get("total")), stat("PASS variants", v.get("pass")), stat("SNPs", v.get("snps")), stat("Indels", v.get("indels")), small_note(VARIANTS_NOTE)])) c = S["clinvar"]["data"] n = c.get("count", 0) by = c.get("by_stars", {}) # Never green: no hit is not an all-clear, and a hit is something to look # at whatever its count, its genotype or its stars. cv_body = [stat("ClinVar matches", badge(n, "yellow" if n else "gray")), stat("By stars (4/3/2/1/0)", E(" / ".join(str(by.get(k, 0)) for k in ("4", "3", "2", "1", "0")))), stat("ClinVar file date", E(s["databases"]["clinvar_release"] or "unknown")), small_note(CLINVAR_FREQ_NOTE)] if "cdna_flagged" in c: cv_body.insert(2, stat("Flagged by the cDNA read check", badge(c["cdna_flagged"], "red" if c["cdna_flagged"] else "gray"))) if c.get("construct_sites"): cv_body.insert(2, stat("Hits at a known lab-construct site (check the reads)", badge(c["construct_sites"], "yellow"))) if c.get("cdna_scan") and not c["cdna_scan"]["note"].startswith("not run"): nl = len(c["cdna_scan"]["loci"]) cv_body.insert(2, stat("Loci with spliced reads (cDNA scan)", badge(nl, "red" if nl else "gray"))) if "low_confidence" in c: f = c.get("call_floor") or {} cv_body.insert(1, stat(f"Low-confidence calls (GQ below {f.get('GQ')} or DP below {f.get('DP')}), not counted", badge(c["low_confidence"], "yellow" if c["low_confidence"] else "gray"))) if clinvar_freq_line(c): cv_body.insert(-1, small_note(clinvar_freq_line(c))) a("clinvar", card(S["clinvar"], "ClinVar Screening", cv_body)) if S.get("carrier", MISSING)["state"] != "missing": car_ok = S["carrier"]["state"] in ("ok", "stale") a("carrier", card(S["carrier"], "Carrier List (this sample)", [f"

{E(line)}

" for line in (carrier_lines(S["carrier"]["data"]) if car_ok else [])] + [f"

{E(CARRIER_NOTE)}

"], full=True)) if S.get("couple", MISSING)["state"] != "missing": a("couple", card(S["couple"], "Couple Carrier Screen", [f"

{E(line)}

" for line in couple_lines(S["couple"]["data"])], full=True)) pg = S["pharmcat"]["data"] cp = S["cpic"]["data"] # Never green: a report that was written is not a finding (the frame's own Complete badge is neutral too). pgx_body = [stat("PharmCAT report", badge("Complete", "state") if S["pharmcat"]["state"] in ("ok", "stale") else badge("Not run", "gray"))] if pg.get("version"): pgx_body.append(stat("PharmCAT version", E(pg["version"]))) if S["pypgx"]["state"] in ("ok", "stale") and "comparison" in S["pypgx"]["data"]: pgx_body.append(stat("PharmCAT vs pypgx conflicts", S["pypgx"]["data"]["comparison"]["conflicts"])) pgx_body.append(small_note(PHARMCAT_NOTE)) a("pharmcat", card(S["pharmcat"], "Pharmacogenomics", pgx_body)) if S["pypgx"]["state"] != "missing": pd = S["pypgx"]["data"] a("pypgx", card(S["pypgx"], "pypgx Pharmacogenomics", [stat("Genes called", f"{pd.get('genes_called')}/{pd.get('genes_total')}"), stat("CYP2D6 diplotype", E(pd.get("cyp2d6") or "not called"))] + [f"

{E(line)}

" for line in pypgx_lines(pd)])) cn_rows = pgx_copy_number(S) if cn_rows: a("pypgx", card(None, "PGx Copy Number", [stat(g, E(v)) for g, v in cn_rows])) cpic_body = [stat("Status", done_badge(S["cpic"]))] if not cp.get("parse_failed"): cpic_body += [stat("Genes with a non-normal phenotype", cp.get("non_normal", 0)), stat("Genes with more than one possible result", cp.get("ambiguous", 0)), stat("Genes not called", cp.get("not_called", 0)), stat("Genes called without a function phenotype (no drug guidance)", cp.get("unclassified", 0))] else: cpic_body.append(stat("PharmCAT report", badge("could not be parsed", "red"))) cpic_body.append(stat("Tip", 'Recommendations per gene: ' f'cpic/{E(s["sample"])}_cpic_recommendations.txt')) cpic_body.append(small_note(CPIC_NOTE)) a("cpic", card(S["cpic"], "CPIC Drug Recommendations", cpic_body)) calls = s["cyp2d6"]["calls"] agree = s["cyp2d6"]["agree"] cy_body = [stat(CYP2D6_LABELS.get(k, k), E(v or "not run")) for k, v in calls.items()] cy_body.append(stat("pypgx and Cyrius agree", badge("yes", "green") if agree else badge("no", "red") if agree is False else badge("fewer than two usable calls", "gray"))) cons = s["cyp2d6"].get("consensus") if cons: cy_body.append(stat("Step 36", badge(cons.get("result") or "?", "state" if cons.get("passed_to_pharmcat") else "yellow"))) cy_body.append(small_note(("Passed to PharmCAT: " if cons.get("passed_to_pharmcat") else "Not passed to PharmCAT: ") + (cons.get("reason") or "no reason given"))) prob = s["cyp2d6"].get("probable") if prob: cy_body.append(stat(prob["label"].capitalize(), E(probable_text(prob)))) cy_body.append(small_note(PGX_CALLERS_NOTE)) a("cyrius", ["
", "

CYP2D6 Across Callers

"] + [f'
{E(S[k]["title"] + ": " + stale_note(S[k]))}
' for k in ("cpic", "pypgx", "cyrius") if S[k]["state"] in ("stale", "failed")] + cy_body + ["
"]) hla = S["hla"]["data"] hla_body = [stat(l["gene"], E(hla_text(l))) for l in hla.get("loci", [])] if hla.get("derived"): hla_body += [small_note(x) for x in hla_derived_lines(hla["derived"])] + [small_note(HLA_DERIVED_NOTE)] hla_body += [stat("HLA database", E(s["databases"]["hla_database"] or "unknown")), small_note(HLA_NOTE)] if hla.get("optitype") is not None: hla_body += [stat(f"{g}: T1K vs OptiType", E(line)) if g else stat("OptiType check", E(line)) for g, line in hla_optitype_lines(hla["optitype"])] if hla.get("kir") is not None: hla_body += [stat(g, E(line)) if g else small_note(line) for g, line in kir_lines(hla["kir"])] hla_body.append(small_note(KIR_NOTE)) a("hla", card(S["hla"], "HLA Typing", hla_body)) if S.get("locityper", MISSING)["state"] != "missing": lt = S["locityper"] body = [] if lt["state"] in ("ok", "stale"): d = lt["data"] body.append(stat("Loci called", E(f"{d['called']} of {len(d['loci'])} ({d['passed']} pass the filter)"))) body.append(" " + "".join(f"" f"" f"" for x in d["loci"]) + "
LocusLocityperFilterPrimary caller
{E(x['locus'])}{E(locityper_text(x))}{badge(x['filter'], {'pass': 'green', 'fail': 'yellow'}.get(x['filter'], 'gray'))}{E(x.get('primary', '.'))}
") body.append(small_note(LOCITYPER_NOTE)) a("locityper", card(lt, "Locityper Second Opinion at Hard Loci", body, full=True)) m, dl, cn, sv = (S[k]["data"] for k in ("manta", "delly", "cnvpytor", "sv_consensus")) sv_body = [stat("Manta SVs (total / PASS)", f"{m.get('total', 'N/A')} / {m.get('pass', 'N/A')}"), stat("Delly SVs (total / PASS)", f"{dl.get('total', 'N/A')} / {dl.get('pass', 'N/A')}"), stat("CNVpytor CNVs", cn.get("total", "N/A")), stat("CNVpytor significant (e-val < 0.01)", cn.get("significant", "N/A"))] if cnvpytor_filtered_text(cn): sv_body += [stat("CNVpytor significant after filters", E(cnvpytor_filtered_text(cn))), small_note(CNVPYTOR_NOTE)] sv_body.append(stat("Consensus SVs (2+ callers)", sv.get("consensus", "N/A"))) sv_body.append(small_note(SV_CALLERS_NOTE)) notes = [f'
{E(S[k]["title"] + ": " + stale_note(S[k]))}
' for k in ("manta", "delly", "cnvpytor", "sv_consensus") if stale_note(S[k])] a("manta", ['
', "

Structural Variants

"] + notes + sv_body + ["
"]) if S.get("annotsv", MISSING)["state"] != "missing": av = S["annotsv"]["data"] body = [stat("Status", done_badge(S["annotsv"]))] + ([small_note(x) for x in annotsv_lines(av)] if av else []) if av.get("rows"): body.append(f" {VIEWER_TH}" + "".join(f"" f"" f"{viewer_td_of(x['sv'])}" for x in av["rows"]) + "
SVClassGenesCallersChecks
{E(x['type'] + ' ' + x['sv'])}{E(x['acmg_class'])}{E(annotsv_genes_text(x))}{E(annotsv_support_text(x))}{E('; '.join(annotsv_flags(x)) or 'none')}
") if av.get("downgraded"): body.append("

Moved to class 3 by step 05's rules

") body.append(" " f"{VIEWER_TH}" + "".join(f"" f"" f"" f"{viewer_td_of(x['sv'])}" for x in av["downgraded"]) + "
SVAnnotSV classClassGenesRuleWhy
{E(x['type'] + ' ' + x['sv'])}{E(x['annotsv_class'])}{E(x['acmg_class'])}{E(annotsv_genes_text(x))}{E(x['rule'] or 'not named')}{E(x['rule_detail'] or 'no detail')}
") if av.get("rows") or av.get("downgraded"): body += [VIEWER_NOTE, small_note(ANNOTSV_NOTE)] a("annotsv", card(S["annotsv"], "Structural Variants, Class 4 and 5 (AnnotSV)", body, full=True)) cs = S["cpsr"]["data"] cpsr_body = [stat("CPSR report", badge("Complete", "state") if cs.get("html_report") else badge("No HTML", "gray"))] for k, val in (cs.get("classification") or {}).items(): cpsr_body.append(stat(k, val)) cpsr_body += [small_note(line.strip()) for line in cpsr_lines(cs, s["databases"])] cpsr_body.append(small_note(CPSR_NOTE)) a("cpsr", card(S["cpsr"], "Cancer Predisposition", cpsr_body)) eh = S["expansions"]["data"] eh_body = [stat("Status", done_badge(S["expansions"]))] if eh.get("stranger_outdated"): eh_body.append(stat("Outside the normal range (Stranger)", badge("older than ExpansionHunter's result: rerun step 9b", "yellow"))) elif not eh.get("stranger"): eh_body.append(stat("Outside the normal range (Stranger)", badge("not run", "gray"))) else: fl = eh.get("flagged") or [] eh_body.append(stat("Outside the normal range (Stranger)", badge(len(fl), "yellow" if fl else "gray"))) if eh.get("unsized"): eh_body.append(stat("Not sized from short reads (not counted as normal)", badge(len(eh["unsized"]), "yellow"))) if eh.get("intermediate"): eh_body.append(stat("In an intermediate range", badge(", ".join(eh["intermediate"]), "yellow"))) if eh.get("not_graded"): eh_body.append(stat("Not graded (no thresholds in the catalog)", badge(", ".join(eh["not_graded"]), "gray"))) eh_body.append(small_note(NOT_GRADED_NOTE)) for r in eh.get("readings") or []: colour = "yellow" if r.get("five_t") or r.get("agreement") == "differs" else "gray" eh_body.append(stat(f"{r['locus']} {r['repeat']}", badge(r["genotype"] if r["status"] == "read" else r["status"].replace("_", " "), colour))) eh_body.append(small_note(f"{r['reading']} ({r['source']})")) for l in eh.get("flagged") or []: if l.get("rfc1_motif"): eh_body.append(small_note(rfc1_text(l["rfc1_motif"]))) eh_body.append(small_note(RFC1_NOTE)) if l.get("motif"): eh_body.append(small_note(motif_text(l["locus"], l["motif"]))) # Every locus, the five key loci first. rows = str_rows(eh) if rows: eh_body.append(" " + "".join(f"" for c in ("Locus", "Repeat Count", "Stranger", "Notes")) + "" + "".join("" + "".join(f"" for x in r) + "" for r in rows) + "
{c}
{E(str(x))}
") eh_body.append(small_note(EH_NOTE)) a("expansions", card(S["expansions"], "Repeat Expansions", eh_body)) r, hg, tl = S["roh"]["data"], S["haplogroup"]["data"], S["telomere"]["data"] a("roh", card(S["roh"], "Runs of Homozygosity", [stat("Status", done_badge(S["roh"])), stat("ROH total", f"{r.get('total_mb', 0):.1f} MB"), stat("ROH largest segment", f"{r.get('largest_mb', 0):.1f} MB"), stat("Segments", r.get("segments", 0)), stat("Autosomal ROH > 5 MB", len(r.get("autosomal_over_5mb", [])))] + [small_note(roh_region(x)) for x in r.get("autosomal_over_5mb", [])] + [small_note(x) for x in roh_lines(r)])) a("haplogroup", card(S["haplogroup"], "Mitochondrial Haplogroup", [stat("Status", done_badge(S["haplogroup"])), stat("Haplogroup", E(hg.get("haplogroup", "."))), stat("Contamination (haplocheck)", E(contamination_text(hg)))] + explore_html(hg))) if S.get("paralogs", MISSING)["state"] != "missing": pg = S["paralogs"]["data"] rows = "".join(f"{E(g['gene'])}{E(g['copy_number'])}{E(g['status'])}" f"{E(g['detail'])}" for g in pg.get("genes", [])) body = [stat("Status", done_badge(S["paralogs"]))] if rows: body.append(" " + rows + "
GeneCopy numberCallDetail
") smn = smn1_text(pg.get("smn1") or {}) if smn: body.append(stat("SMN1 by both tools", E(smn))) if pg.get("other_regions"): body.append(stat("Other Paraphase regions", f"{pg['other_regions']} ({pg['other_regions_called']} with a call)")) body.append(stat("Variants on phased haplotypes", sum(pg.get("variants", {}).values()))) body.append(small_note(PARALOG_NOTE)) a("paralogs", card(S["paralogs"], "Paralog Genes (Paraphase)", body, full=True)) if S.get("parascopy", MISSING)["state"] != "missing": a("parascopy", card(S["parascopy"], "SMN1/SMN2 Copy Number (Parascopy)", [stat("Status", done_badge(S["parascopy"]))] + [stat(*(E(x) for x in line.split(": ", 1))) for line in parascopy_lines(S["parascopy"]["data"])] + parascopy_loci_html(S["parascopy"]["data"]) + cn_intervals_html(S["parascopy"]["data"].get("cn_intervals")) + [small_note(PARASCOPY_NOTE)])) unchecked = paralogs_unchecked(S) if unchecked: a("paralogs", card(None, "Paralog Copy Number", [stat("Status", badge("Not checked", "gray")), small_note(unchecked)])) if S.get("y_haplogroup", MISSING)["state"] != "missing": yh = S["y_haplogroup"]["data"] a("y_haplogroup", card(S["y_haplogroup"], "Y-Chromosome Haplogroup", [stat("Haplogroup", E(yh.get("haplogroup", "."))), stat("Markers", E(str(yh.get("valid_markers", ".")))), stat("QC-score", E(str(yh.get("qc_score", "."))))] + explore_html(yh))) if S.get("y_tree", MISSING)["state"] != "missing": yt = S["y_tree"] a("y_tree", card(yt, "Y Placement on the Current Public Tree", y_tree_body(yt["data"]) if yt["state"] in ("ok", "stale") else [], full=True)) if S.get("y_str", MISSING)["state"] != "missing": ys = S["y_str"] a("y_str", card(ys, "Y-STR Markers (HipSTR)", ystr_body(ys["data"]) if ys["state"] in ("ok", "stale") else [], full=True)) if S.get("consumer_export", MISSING)["state"] != "missing": a("consumer_export", card(S["consumer_export"], "Raw-Data Export (23andMe v5 layout)", [f"

{E(line)}

" for line in consumer_export_lines(S["consumer_export"]["data"])])) if S.get("bloodtype", MISSING)["state"] != "missing": a("bloodtype", card(S["bloodtype"], "Blood Groups (predicted)", bloodtype_body(S["bloodtype"]["data"]), full=True)) if S.get("archaic", MISSING)["state"] != "missing": ah = S["archaic"]["data"] a("archaic", card(S["archaic"], "Archaic Ancestry (Neanderthal, Denisovan)", [stat("Neanderthal", E(f"{ah['neanderthal_percent']}%")), stat("Denisovan", E(f"{ah['denisovan_percent']}%"))] + [f"

{E(line)}

" for line in archaic_lines(ah)] + [small_note(ARCHAIC_NOTE)] if S["archaic"]["state"] in ("ok", "stale") else [])) if S.get("lpa", MISSING)["state"] != "missing": lp = S["lpa"]["data"] a("lpa", card(S["lpa"], "Lp(a): LPA KIV-2 Repeat Count", ([stat("Genetic sign of high Lp(a)", badge("Yes", "yellow"))] if lp.get("flag") == "high" else []) + [f"

{E(line)}

" for line in lpa_lines(lp)] + [small_note(LPA_NOTE)])) if S.get("vntyper", MISSING)["state"] != "missing": vn = S["vntyper"]["data"] a("vntyper", card(S["vntyper"], "MUC1 VNTR Frameshifts (VNtyper)", ([stat("Result", badge(vn.get("status", "."), {"positive": "red", "possible": "yellow", "negative": "green"}.get(vn.get("status"), "gray")))]) + [f"

{E(line)}

" for line in vntyper_lines(vn)] + [small_note(VNTYPER_NOTE)])) if S.get("viral", MISSING)["state"] != "missing": a("viral", card(S["viral"], "Viral DNA in the Unmapped Reads", viral_body(S["viral"]["data"]), full=True)) if S.get("chip", MISSING)["state"] != "missing": ch = S["chip"]["data"] # the card shows its body only for a section that was read a("chip", card(S["chip"], "Clonal Haematopoiesis (CHIP)", [stat("CHIP calls", E(str(len(ch.get("calls", [])))))] + [f"

{E(line)}

" for line in chip_lines(ch, s["sample"])[:-1]] + [small_note(CHIP_NOTE)], full=True)) if S.get("mei", MISSING)["state"] != "missing": a("mei", card(S["mei"], "Mobile Element Insertions", mei_body(S["mei"]["data"]), full=True)) if S.get("mosaic", MISSING)["state"] != "missing": mo = S["mosaic"] a("mosaic", card(mo, "Mosaic Chromosomal Alterations (MoChA)", mosaic_mca_body(mo["data"]) if mo["state"] in ("ok", "stale") else [], full=True)) a("telomere", card(S["telomere"], "Telomere content (relative)", [stat("Telomere content", E(str(tl.get("tel_content", "."))))] + [stat("Warning", badge(x[len("WARNING: "):], "yellow")) if x.startswith("WARNING: ") else small_note(x) for x in telomere_lines(tl)] + [small_note(TELOMERE_NOTE)])) mi = S["mito"]["data"] ma = mi.get("annotation") or {} mito_body = [stat("chrM variants (PASS)", mi.get("pass")), stat("Heteroplasmic (AF 0.05 to 0.95, outside the D-loop poly-C tracts)", mi.get("heteroplasmic")), stat("Length heteroplasmy in the D-loop poly-C tracts", len(mi.get("polyc_heteroplasmic") or []))] mito_body += [small_note(f"{x['variant']} AF {x['af']}") for x in mi.get("polyc_heteroplasmic") or []] if mi.get("polyc_heteroplasmic"): mito_body.append(small_note(MITO_POLYC_NOTE)) if ma.get("source"): plp = ma.get("clinvar_plp", 0) mito_body.append(stat("ClinVar pathogenic or likely pathogenic", badge(plp, "yellow" if plp else "gray"))) if ma.get("variants"): mito_body.append(" " + "".join(f"" for c in ( "Variant", "AF", "ClinVar", "Review", "Condition", "gnomAD AF hom", "gnomAD AF het", "Poly-C tract")) + VIEWER_TH + "" + "".join( "" + "".join(f"" for x in ( f"chrM:{v['pos']} {v['ref']}>{v['alt']}", v.get("af"), v.get("clinvar_significance"), v.get("clinvar_review"), v.get("clinvar_condition"), v.get("gnomad_af_hom"), v.get("gnomad_af_het"), "yes" if v.get("polyc") else "")) + viewer_td("chrM", v["pos"]) + "" for v in ma["variants"]) + "
{c}
{E(str(x))}
") mito_body.append(VIEWER_NOTE) mito_body.append(small_note(f"ClinVar {ma.get('clinvar') or 'unknown'}; gnomAD {ma.get('gnomad') or 'unknown'}")) elif ma.get("note"): mito_body.append(small_note(f"ClinVar and gnomAD: not annotated ({ma['note']})")) if "confirmed" in mi: n = len(mi["confirmed"]) mito_body.append(stat("Confirmed disease variants", badge(n, "yellow" if n else "gray"))) mito_body += [small_note(mito_confirmed_text(v)) for v in mi["confirmed"]] dl = mi.get("deletions") if dl: named = sum(1 for r in dl["listed"] if r.get("known")) mito_body.append(stat("Large deletions (eKLIPse)", dl["total"])) mito_body.append(stat("Named in the confirmed list", badge(named, "yellow" if named else "gray"))) mito_body += [small_note(mito_deletion_text(r)) for r in dl["listed"]] mito_body.append(small_note(MITO_DELETION_NOTE)) elif mi.get("deletions_note"): mito_body.append(small_note(f"Large deletions: not looked for ({mi['deletions_note']})")) if mi.get("copies"): # mc, not c: c holds the ClinVar data the hits table below reads. mc = mi["copies"] mito_body.append(stat("mtDNA copies per cell", E(str(mc["mtdna_copies"])) if mc.get("status") == "called" else "not assessed")) mito_body.append(small_note(mito_copies_text(mc))) if mc.get("status") == "called": mito_body.append(small_note(MITO_COPIES_NOTE)) elif mi.get("copies_note"): mito_body.append(small_note(f"mtDNA copy number: not counted ({mi['copies_note']})")) mito_body.append(small_note(MITO_NOTE)) a("mito", card(S["mito"], "Mitochondrial Analysis", mito_body, full=bool(ma.get("variants")))) cl = S["clinical"]["data"] a("clinical", card(S["clinical"], "Clinical Variant Filter", [stat("Total interesting variants", cl.get("variants"))] + ([stat("Genes", cl["genes"])] if "genes" in cl else []) + [stat(f"{k} impact", v) for k, v in sorted((cl.get("by_impact") or {}).items())] + ([stat("Frequency unknown (not rare)", cl["frequency_unknown"])] if "frequency_unknown" in cl else []) + ([stat("Weak genotype calls", cl["weak_calls"])] if "weak_calls" in cl else []))) sf = cl.get("acmg_sf") if sf and (sf["clinvar_hits"] or sf["high_impact"] or sf.get("structural") or sf.get("not_reported") or sf.get("unavailable")): rows = "".join(f"{E(g)}{E(v)}{E(z)}{E(ev)}{viewer_td_of(v)}\n" for g, v, z, ev in sf_rows(sf)) a("clinical", card(S["clinical"], f"Secondary-Findings Genes ({sf['version']})", [" ", f" {VIEWER_TH}", rows.rstrip("\n"), "
GeneVariantGenotypeEvidence
"] + [f"

{E(line)}

" for line in sf_apart_lines(sf)] + ([VIEWER_NOTE] if rows else []) + [f"

{E(ACMG_NOTE)}

"], full=True)) sl = S["slivar"]["data"] sl_body = [stat("Prioritized variants", sl.get("prioritized"))] if "frequency_unknown" in sl: sl_body.append(stat("Frequency unknown (not rare)", sl["frequency_unknown"])) if "compound_het_variants" in sl: sl_body.append(stat("Compound het candidates", f"{sl['compound_het_variants']} variants, {sl['compound_het_genes']} genes")) if "compound_het_phase" in sl: sl_body += comphet_phase_html(sl) a("slivar", card(S["slivar"], "Variant Prioritization (slivar)", sl_body)) if S["prs"]["state"] in ("ok", "stale"): d = S["prs"]["data"] # The effect column only when the table names evaluations (Evaluated_In). show_effect = d.get("adjusted") and any(x.get("evaluated_in") is not None for x in d["scores"]) rows = "".join(f"{E(x['condition'])}{E(x['pgs_id'])}{E(x['score'])}" f"{E(x['matched'])}/{E(x['total'])}" f"{E(prs_percentile(x) or 'raw score only')}" + (f"{E(prs_effect(x))}" if show_effect else "") + "\n" for x in d["scores"]) effect_th = "Effect in your group" if show_effect else "" a("prs", card(S["prs"], "Polygenic Risk Scores" + ("" if d.get("adjusted") else " (raw, not percentiles)"), [" ", " " f"{effect_th}", rows.rstrip("\n"), "
ConditionPGSScoreVariants matchedPercentile
", f"

{E(prs_note(d))}

"], full=True)) if S.get("ancestry_fine", MISSING)["state"] != "missing": d = S["ancestry_fine"]["data"] body = [] for level, title in ANCESTRY_FINE_LEVELS: rows = "".join(f"{E(r['group'])}{E(share(r['fraction']))}" f"{E(ancestry_fine_spread(r).strip(' ()') or '.')}\n" for r in ancestry_fine_rows(d, level)) if rows: body += [f"

{E(title)}

", " ", " ", rows.rstrip("\n"), "
GroupFractionBootstrap range
"] if ancestry_fine_left_out(d): body.append(f"

{E(ancestry_fine_left_out(d))}

") body.append(stat("Painted genome", E(ancestry_fine_painted(d)))) if d.get("painting_png"): body.append(f' Chromosome painting: chromosomes 1 to 22, two haplotypes each, coloured by '
                        f'continental group') body.append("

" + " ".join(f'■ {E(x["group"])}' for x in d.get("legend", [])) + " ■ not painted

") body.append(f"

{E(ANCESTRY_FINE_NOTE)}

") a("ancestry_fine", card(S["ancestry_fine"], "Fine-Grained Ancestry", body, full=True)) tr_sec = S.get("traits", MISSING) a("traits", card(tr_sec, "Traits", traits_html(tr_sec["data"], s["sample"]) if tr_sec["state"] in ("ok", "stale") else [], full=True)) ex_sec = S.get("exomiser", MISSING) if ex_sec["state"] != "missing": a("exomiser", card(ex_sec, "Symptom-Driven Ranking (Exomiser)", exomiser_html(ex_sec["data"], s["sample"]) if ex_sec["state"] in ("ok", "stale") else [], full=True)) if S.get("ancient", MISSING)["state"] != "missing": d = S["ancient"]["data"] lines = ancient_lines(d) rows = "".join(f"{E(str(r['rank']))}{E(r['group'])}{E(r['dates'])}" f"{E(r['country'])}{E(r['locality'])}{E(str(r['n']))}\n" for r in (d.get("nearest") or [])[:10]) body = [f"

{E(lines[0])}

", " ", " ", rows.rstrip("\n"), "
#Ancient groupDatesCountryPlacePeople
"] if d.get("plot_svg"): # An of the SVG: shown, never run as part of the page. body.append(' PC1 against PC2: present-day West Eurasians in grey, ancient people coloured by '
                        f'age, the sample marked') body.append(f"

{E(ANCIENT_NOTE)}

") a("ancient", card(S["ancient"], "Ancient Populations", body, full=True)) if S["cpic"]["state"] in ("ok", "stale") and (cp["non_normal"] or cp.get("ambiguous")): rows = "".join(f"{E(g['gene'])}{E(g['diplotype'])}{E(g['phenotype'])}\n" for g in cp["genes"] if g["status"] in ("non-normal", "ambiguous")) body = [" ", " ", rows.rstrip("\n"), "
GeneDiplotypePhenotype
"] body += [f'
WARNING: {E(x)}
' for x in cp["warnings"]] body.append(f"

Drugs for each gene: cpic/{E(s['sample'])}_cpic_recommendations.txt

") a("cpic", card(S["cpic"], "Genes With a Non-Normal or Unresolved Phenotype (CPIC)", body, full=True)) if S["clinvar"]["state"] in ("ok", "stale") and c.get("hits"): # The combined-allele cell is empty, not '.', for a hit that is # neither a combined allele nor part of one: no note is no missing data. # The cDNA read check column only when step 06 wrote its table. reads = "cdna_flagged" in c # The frequency and call columns only for a summary that carries them. freq = "frequency" in c call = "low_confidence" in c nh = len(c["hits"]) rows = [f"{E(h['chrom'])}{h['pos']}{E(h['ref'])}{E(h['alt'])}" f"{E(h['genotype'])}{E(h['gene'])}{E(h['significance'])}" f"{E(h['review_status'])}{h['stars']}" f"{E(combined_cell(h))}" + (f"{E(af_text(h))}" if freq else "") + (f"{E(call_text(h))}" if call else "") + (f"{E(cdna_text(h))}" if reads else "") + viewer_td(h["chrom"], h["pos"]) + "" for h in c["hits"][:report_charts.HITS_SHOWN]] a("clinvar", card(S["clinvar"], f"ClinVar Hits (best-reviewed first, {min(nh, 50)} of {nh})", # The anchor the charts link a listed hit to (report_charts.hit_anchor). [f' ', " ", " " "" + ("" if freq else "") + ("" if call else "") + ("" if reads else "") + VIEWER_TH + ""] + [" " + x for x in rows] + ["
ChrPositionRefAltGenotypeGeneSignificanceReview statusStarsCombined allelegnomAD frequencyCall qualitycDNA read check
"] + [small_note("Hit at a known lab-construct site past the first 50: " + construct_past_cap_text(h)) for h in construct_past_cap(c["hits"], report_charts.HITS_SHOWN)] + ([VIEWER_NOTE] if rows else []), full=True)) if S["clinvar"]["state"] in ("ok", "stale") and ("deep_intronic" in c or c.get("cdna_scan")): body = [] if "deep_intronic" in c: body += [" ", f" {VIEWER_TH}"] body += [f" " f"" f"{viewer_td(x['chrom'], x['pos'])}" for x in c["deep_intronic"]] body += ["
GeneVariantPositionCall
{E(x['gene'])}{E(x['hgvs'])}{E(x['chrom'])}:{x['pos']} {E(x['ref'])}>{E(x['alt'])}{E(deep_intronic_call(x))}
", VIEWER_NOTE, small_note(DEEP_INTRONIC_NOTE)] scan = cdna_scan_lines(c) if scan: body.append(f"

{E(scan[0])}

") if len(scan) > 1: body += [" ", f" {VIEWER_TH}"] body += [f" " f"{viewer_td(x['chrom'], x['start'], x['end'])}" for x in c["cdna_scan"]["loci"][:20]] body += ["
LocusJunctionsReads
{E(x['chrom'])}:{x['start']}-{x['end']}{x['junctions']}{x['reads']}
", VIEWER_NOTE, small_note(CDNA_SCAN_NOTE)] a("clinvar", card(S["clinvar"], "Known Deep Intronic Sites and the cDNA Scan", body, full=True)) add_charts(parts, chart_specs(s)) return html_page(s, parts, index if index is not None else results_index.build(s, anchors=SECTION_OF)) # --- charts -------------------------------------------------------------------------- def chart_specs(s): """The report's charts (bin/report_charts.py), with this file's caveats and helpers.""" notes = {k: v for k, v in globals().items() if k.endswith("_NOTE") and isinstance(v, str)} helpers = {"ancestry_fine_rows": ancestry_fine_rows, "ANCESTRY_FINE_LEVELS": ANCESTRY_FINE_LEVELS, "prs_percentile": prs_percentile, "prs_note": prs_note, "PRS_NOT_APPLICABLE": PRS_NOT_APPLICABLE} return report_charts.build(s, notes, helpers) def add_charts(parts, specs): """Each chart's SVG into its section, below its caveat: right under the first card title when the caveat is a note line hoist_caveats() moves up there, else right after the paragraph the caveat is part of (PRS). A text-only chart (PRS without a panel) is the note the card already prints, so the HTML report leaves it out; the live page shows it.""" for sp in specs: lines = parts.get(SECTION_OF[sp["section"]]) if sp["kind"] == "text" or not lines: continue cav = E(sp["caveat"]) inside = [i for i, x in enumerate(lines) if cav in x and not notes_in(x.strip(), {})] at = (inside[0] if inside else next(i for i, x in enumerate(lines) if x.strip().startswith("

"))) + 1 lines.insert(at, f'
{sp["svg"]}
') def charts_json(s): return {"schema_version": report_charts.SCHEMA_VERSION, "sample": s["sample"], "generated_utc": s["generated_utc"], "charts": chart_specs(s)} # --- html page: chapters, contents, section frames ----------------------------- CSP = "default-src 'none'; img-src data:; style-src 'unsafe-inline'" STEP_OF = {k: step for k, _, step, _ in collect_summary.SECTIONS} # A section's state from the states of its keys. Never green: a section that # ran is not a finding, and the ClinVar section must show no green at all. STATE_BADGE = {"ok": ("Complete", "state"), "stale": ("Stale", "yellow"), "failed": ("Failed", "red"), "part": ("Part failed", "red"), "incomplete": ("Part not run", "yellow"), "missing": ("Not run", "gray")} LIMITS = ("limits", "What this report leaves out", "Which steps did not run, and what does no step look at?") def frame_state(secs): st = {x["state"] for x in secs} if st & {"failed", "unreadable"}: return "part" if st & {"ok", "stale"} else "failed" if "stale" in st: return "stale" # A section whose steps did not all run is not complete. return ("incomplete" if "missing" in st else "ok") if "ok" in st else "missing" def caveat_notes(): """Every *_NOTE sentence of this file: shown under the card title it belongs to.""" return [v for k, v in globals().items() if k.endswith("_NOTE") and isinstance(v, str)] def hoist_caveats(lines, meta): """The card lines of one section with META under the first card title and each *_NOTE line a card prints moved up to right under that card's title.""" notes = {} for n in caveat_notes(): notes[small_note(n).strip()] = n notes[f"

{E(n)}

"] = n out, pos = [], None for line in lines: st = line.strip() if st.startswith("

"): out.append(line) if meta: out.append(meta) meta = None pos = len(out) elif pos is not None and (found := notes_in(st, notes)): for n in found: out.insert(pos, f'

{E(n)}

') pos += 1 else: out.append(line) return out def notes_in(line, notes): """The *_NOTE sentences a note line is made of: one, or several joined by spaces (step 11's F_ROH and band notes); [] when it holds anything else.""" if line in notes: return [notes[line]] m = re.fullmatch(r'

(.*)

', line) rest, found = m.group(1) if m else "", [] while rest: n = next((n for n in caveat_notes() if rest == E(n) or rest.startswith(E(n) + " ")), None) if n is None: return [] found.append(n) rest = rest[len(E(n)) + 1:] return found def step_files(S, sample, sid): """(relative path, label) of the step's own files beside this report, from the summary: the report sits in the sample folder, as each step's output does (scripts/24-html-report.sh, and publishDir in the Nextflow modules).""" def ran(k): return S.get(k, MISSING)["state"] in ("ok", "stale") and S[k].get("source") out = [] if sid == "pharmcat" and ran("pharmcat") and S["pharmcat"]["data"].get("html_report"): out.append((S["pharmcat"]["source"][:-len(".json")] + ".html", "PharmCAT HTML report")) if sid == "cpic" and ran("cpic"): out.append((os.path.join(os.path.dirname(S["cpic"]["source"]), f"{sample}_cpic_recommendations.txt"), "CPIC recommendations per gene (text)")) if sid == "cpsr" and ran("cpsr") and S["cpsr"]["data"].get("html_report"): src = S["cpsr"]["source"] out.append((src, "CPSR HTML report") if src.endswith(".html") else (os.path.dirname(src) + "/", "the cpsr folder, which holds the CPSR HTML report")) if sid == "exomiser" and ran("exomiser"): out.append((S["exomiser"]["source"], "Exomiser ranking table")) return out def frame(S, sample, sid, lines, keys=None, always=False, since=None): """One section: an anchor, the step, state and file date under its first card title (and "New since " when its result changed since the previous run), each caveat under its card's title, the cards, then links to the step's own files.""" secs = [S.get(k, MISSING) for k in keys or ()] meta = None if keys: steps = list(dict.fromkeys(STEP_OF[k] for k in keys)) label, colour = STATE_BADGE[frame_state(secs)] dates = [x["file_date"] for x in secs if x.get("file_date")] meta = (f'

Step{"s" if len(steps) > 1 else ""} {E(", ".join(steps))} · ' f"{badge(label, colour)}" + (f" · file date {E(max(dates))}" if dates else "") + (f" · {badge(f'New since {since}', 'yellow')}" if since else "") + f' · link to this section

') wide = len([x for x in lines if x.strip().startswith("

")]) > 1 or any(x.startswith('
'] + hoist_caveats(lines, meta) + (['

Files of this step, beside this report: ' + " · ".join(f'{E(t)}' for h, t in files) + "

"] if files else []) + [" "]) def limits_cards(s): not_run = ['
', "

Steps Not Run

"] not_run += (['
    '] + [f"
  • {E(t)}
  • " for t in s["not_run"]] + ["
"] if s["not_run"] else ["

All major steps completed.

"]) not_assessed = ['
', "

Not Assessed by This Pipeline

", '
    '] not_assessed += [f"
  • {E(t)}
  • " for t in s["not_assessed"]] + ["
"] return not_run + ["
"], not_assessed + ["
"] TERMS = ("terms", "Genes and rsIDs in these results", "Where in this report does a gene or an rsID come up?") def terms_appendix(index, parts): """The closing appendix: one line per gene symbol or rsID of the search index, with a link to each section that names it. No script: the browser's find (Ctrl+F) searches it; the live site's search box filters the same index.""" terms = index.get("terms") or {} # No card title: the chapter title above names it (and the cards' titles are tests/test_render_report.py's list). body = ['
', '

Every gene symbol and rsID a section of this report names, with the sections that ' "name it and how many times. A gene listed here is a gene the results mention, not a finding: open the " "section to see what it says. The genes of the clinical filter (step 23) and variant prioritization " "(step 31) come from their tables, which the report counts but does not list.

"] if not terms: body.append("

No section of this report names a gene or an rsID.

") else: body.append('
    ') for term, items in terms.items(): links = [] for it in items: label = E(it["title"]) + (" (stale)" if it["state"] == "stale" else "") a = it.get("anchor") links.append((f'{label}' if a and parts.get(a) else label) + (f" ({it['count']})" if it["count"] > 1 else "")) body.append(f"
  • {E(term)}: {', '.join(links)}
  • ") body.append("
") return body + ["
"] def html_page(s, parts, index=None): S = s["sections"] m = s["manifest"] commit = next((r[2] for r in m if r[0] == "run" and r[1] == "git_commit"), None) if m else None db = s["databases"] ns = s.get("new_since") or {} changed = set(ns.get("sections") or []) toc, body = ['
", ""] cid, title, question = LIMITS not_run, not_assessed = limits_cards(s) toc += [f'
  • {E(title)}', "
      ", '
    1. Steps not run
    2. ', '
    3. Not assessed
    4. ', "
    ", "
  • ", " ", ""] body += [f'
    ', f'

    {E(title)}

    ', f'

    {E(question)}

    ', '
    '] body += frame(S, s["sample"], "not-run", not_run) + frame(S, s["sample"], "not-assessed", not_assessed, always=True) body += ["
    ", "
    "] if index is not None: cid, title, question = TERMS toc.insert(-2, f'
  • {E(title)}
  • ') body += [f'
    ', f'

    {E(title)}

    ', f'

    {E(question)}

    ', '
    '] body += frame(S, s["sample"], "terms-list", terms_appendix(index, parts)) body += ["
    ", "
    "] out = ["", '', "", '', f'', '', "OwnGenome Report", "", "", "", '
    '] + toc + [ "
    ", '
    ', "

    Genomic Analysis Report

    ", '
    ', f" Sample: {E(s['sample'])}  |  Generated: {E(s['generated_utc'])}" + (f"  |  Latest run: {E(s['run']['started_utc'])}" if s["run"]["started_utc"] else ""), "
    ", '
    ', f" Pipeline commit: {E(commit or 'unknown')}  |  ClinVar file: {E(db['clinvar_release'] or 'unknown')}" f"  |  ClinVar in CPSR's bundle: {E(db['cpsr_clinvar_release'] or 'unknown')}" f"  |  HLA database: {E(db['hla_database'] or 'unknown')}", "
    "] + ([f'
    {E(recheck_line(s["recheck"]))}
    '] if s.get("recheck") else []) + [ "
    ", '"] out += body out += ['
    ', " Disclaimer: This report is for educational and research purposes only.", " It is not a clinical diagnosis. Always discuss genomic findings with a qualified healthcare", " professional before making any medical decisions. Variants of Uncertain Significance (VUS)", " are not clinically actionable.", "
    ", "", '", "
    ", "
    ", "", ""] return "\n".join(out) + "\n" def write(path, text): tmp = path + ".tmp" with open(tmp, "w") as f: f.write(text) os.replace(tmp, path) def main(argv=None): ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) ap.add_argument("--summary", help="read this summary JSON instead of collecting one") ap.add_argument("--sample") ap.add_argument("--sample-dir") ap.add_argument("--json", help="where to write the collected summary (default SAMPLE_DIR/summary.json)") ap.add_argument("--declared-sex", help="the samplesheet's sex, when no run status or manifest records it") ap.add_argument("--assets", help="the folder holding acmg_sf.tsv and carrier_genes.tsv " "(default: the repository's assets/ beside bin/)") ap.add_argument("-o", "--out", action="append", default=[], help="report to write: .txt for text, .html for HTML (repeatable)") ap.add_argument("--search-index", help="also write every gene and rsID the results mention, with the " "sections that name them, to this JSON file (the live site's search)") ap.add_argument("--charts-json", help="also write the report's charts, as data and SVG, to this JSON file " "(the live page reads it)") a = ap.parse_args(argv) for o in a.out: if not o.endswith((".txt", ".html")): ap.error(f"-o {o}: the name must end in .txt or .html") if a.summary: with open(a.summary) as f: s = json.load(f) elif a.sample and a.sample_dir: if a.assets: collect_summary.ASSETS_DIR = a.assets s = collect_summary.collect(a.sample, a.sample_dir, a.declared_sex) write(a.json or os.path.join(a.sample_dir, "summary.json"), json.dumps(s, indent=1) + "\n") else: ap.error("give --summary, or --sample and --sample-dir") # Only the HTML report and --search-index read the index: a text-only run # does not read the step 23 and 31 tables. need_index = bool(a.search_index) or any(o.endswith(".html") for o in a.out) index = results_index.build(s, a.sample_dir, SECTION_OF) if need_index else None for o in a.out: write(o, text_report(s) if o.endswith(".txt") else html_report(s, index)) if a.search_index: write(a.search_index, json.dumps(index, indent=1) + "\n") if a.charts_json: write(a.charts_json, json.dumps(charts_json(s), indent=1) + "\n") states = {} for sec in s["sections"].values(): states[sec["state"]] = states.get(sec["state"], 0) + 1 print("Sections: " + ", ".join(f"{k} {v}" for k, v in sorted(states.items()))) return 0 if __name__ == "__main__": sys.exit(main())