")
body = [stat("Symptoms searched", E(exomiser_terms(d)))]
if rows:
body += ["
", "
Rank
Gene
Inheritance
Score
"
"
Symptom match
Variant
ACMG (Exomiser)
Linked disease
"
f"{VIEWER_TH}
"]
body += rows + ["
", 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"
",
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 = "
Trait
Gene
Genotype
Reading
Source
"
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"
Gene
Pair in trans
Reads
{VIEWER_TH}
"]
out += [f"
{E(x['gene'])}
{E(x['variants'])}
{E(x['reads'])}
"
f"{viewer_td_of(x['variants'])}
" for x in trans]
out += ["
", 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")
release = next((r[2] for r in m if r[0] == "run" and r[1] == "pipeline_version"), None)
w(f"Run manifest: run_manifest.tsv ({f'OwnGenome {release}, ' if release else ''}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 {}
mk = d.get("smn1_marker")
marker = ([f"SMN1 g.27134T>G silent-carrier marker ({mk.get('rsid') or '.'}): {marker_state(mk)}",
f"SMN1 marker reading: {mk.get('message', '.')}",
f"SMN1 marker caveat: {SMN1_MARKER_CAVEAT}"] if mk else [])
return [f"SMN1 copies: {smn1.get('text', '.')}"] + marker + [
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("
Region
Row
Place
Copies
Change
"
+ rows + "
")
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 ["
Genes
Copies together (agCN)
Reading
" + rows + "
",
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 (og summary collect, two_hits.rs), 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 og y tree-place. 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("
Level
Branch
Derived
Ancestral
"
"
No call
Ancestral SNPs
" + rows + "
")
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))}
",
"
Panel
Marker
Repeats
Confidence
" + rows + "
",
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", "."))),
"
System
Predicted phenotype
Genotype
Confidence
"
+ rows + "
", 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', '.')}")
na = d.get("null_allele")
if na:
out += [f"KIV-2 4925G>A null allele ({(na.get('rsid') or '.').split(' ')[0]}): {marker_state(na)}",
f" {na.get('message', '.')}", f" {LPA_NULL_CAVEAT}"]
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 = ("
Virus
Call
Reads
Breadth
Depth / human
"
"
Copies per cell
" + rows + "
") 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 = ("
Gene
Element
Condition
Inheritance
Status
"
"
Depth
Call
" + rows + "
")
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"
Type
Arm
Region
Mb
Cell fraction
{VIEWER_TH}
"
+ rows + "
\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'
")
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"
" 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("
")
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"
SV
Class
Genes
Callers
Checks
{VIEWER_TH}
"
+ "".join(f"
{E(x['type'] + ' ' + x['sv'])}
{E(x['acmg_class'])}
"
f"
{E(annotsv_genes_text(x))}
{E(annotsv_support_text(x))}
"
f"
{E('; '.join(annotsv_flags(x)) or 'none')}
{viewer_td_of(x['sv'])}
"
for x in av["rows"])
+ "
")
if av.get("downgraded"):
body.append("
Moved to class 3 by step 05's rules
")
body.append("
SV
AnnotSV class
Class
Genes
Rule
"
f"
Why
{VIEWER_TH}
"
+ "".join(f"
{E(x['type'] + ' ' + x['sv'])}
{E(x['annotsv_class'])}
"
f"
{E(x['acmg_class'])}
{E(annotsv_genes_text(x))}
"
f"
{E(x['rule'] or 'not named')}
{E(x['rule_detail'] or 'no detail')}
"
f"{viewer_td_of(x['sv'])}
"
for x in av["downgraded"])
+ "
")
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"
{c}
" for c in ("Locus", "Repeat Count", "Stranger", "Notes"))
+ "
"
+ "".join("
" + "".join(f"
{E(str(x))}
" for x in r) + "
" for r in rows)
+ "
")
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("
Gene
Copy number
Call
Detail
"
+ rows + "
")
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 escapes the label itself; the value is escaped here
+ [stat(lab, E(val)) for lab, val 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"
{c}
" for c in (
"Variant", "AF", "ClinVar", "Review", "Condition", "gnomAD AF hom", "gnomAD AF het", "Poly-C tract"))
+ VIEWER_TH + "
" + "".join(
"
" + "".join(f"
{E(str(x))}
" 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"]) + "
")
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"
Gene
Variant
Genotype
Evidence
{VIEWER_TH}
",
rows.rstrip("\n"), "
"]
+ [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)"),
["
", "
Condition
PGS
Score
Variants matched
Percentile
"
f"{effect_th}
",
rows.rstrip("\n"), "
", 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)}
", "
",
"
Group
Fraction
Bootstrap range
",
rows.rstrip("\n"), "
"]
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' ')
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])}
", "
",
"
#
Ancient group
Dates
Country
Place
People
",
rows.rstrip("\n"), "
"]
if d.get("plot_svg"):
# An of the SVG: shown, never run as part of the page.
body.append(' ')
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 = ["
", "
Gene
Diplotype
Phenotype
", rows.rstrip("\n"),
"
"]
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' ', "
",
"
Chr
Position
Ref
Alt
Genotype
Gene
"
"
Significance
Review status
Stars
Combined allele
"
+ ("
gnomAD frequency
" if freq else "")
+ ("
Call quality
" if call else "")
+ ("
cDNA read check
" if reads else "") + VIEWER_TH + "
"]
+ [" " + x for x in rows] + ["
"]
+ [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 += ["
", 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"
Locus
Junctions
Reads
{VIEWER_TH}
"]
body += [f"
{E(x['chrom'])}:{x['start']}-{x['end']}
{x['junctions']}
"
f"
{x['reads']}
{viewer_td(x['chrom'], x['start'], x['end'])}
"
for x in c["cdna_scan"]["loci"][:20]]
body += ["
", 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) + "
"]
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
# The OwnGenome release the run declared (nextflow.config's manifest.version), when the manifest records it.
release = next((r[2] for r in m if r[0] == "run" and r[1] == "pipeline_version"), None) if m else None
db = s["databases"]
ns = s.get("new_since") or {}
changed = set(ns.get("sections") or [])
toc, body = ['"]
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'
',
(f" OwnGenome release: {E(release)} | " if release 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 []) + [
"",
'
To print one section, open it from the contents (or its "link to this section"), '
"then print: the printout holds that section, this header, the list of what is not assessed and the "
"disclaimer. A chapter prints the same way. In a browser without CSS :has() the whole report prints.
"]
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
try:
s = collect_summary.collect(a.sample, a.sample_dir, a.declared_sex,
out=a.json or os.path.join(a.sample_dir, "summary.json"))
except RuntimeError as e:
sys.exit(f"ERROR: {e}")
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())