Skip to content

Handle recombinant parents given in unaliased form - #319

Open
jchorl wants to merge 1 commit into
andersen-lab:mainfrom
jchorl:fix-unaliased-recombinant-parents
Open

Handle recombinant parents given in unaliased form#319
jchorl wants to merge 1 commit into
andersen-lab:mainfrom
jchorl:fix-unaliased-recombinant-parents

Conversation

@jchorl

@jchorl jchorl commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Problem

freyja demix --depthcutoff <n> crashes for any sample whose barcodes
collapse a group containing XHD:

File "freyja/utils.py", line 1125, in collapse_barcodes
    parent_aliases.append([lineage_data[lin]['alias'] for lin in parents])
KeyError: 'XDV.1.5.1.1.8.1'

collapse_barcodes looks up recombinant parents by lineage name, but
pango-designation's alias_key.json lists XHD's parents as
["XFG.3.4.1", "XDV.1.5.1.1.8.1"] — the second being the unaliased form of
NB.1.8.1, which is only ever an alias: value in lineages.yml, never a
name:. XHD is the only entry in alias_key.json with this inconsistency
(lineage_notes.txt correctly says "Recombinant lineage of XFG.3.4.1,
NB.1.8.1"), and it entered the barcodes with the 08_27_2026 update.

Low-coverage samples hit this readily: at --depthcutoff 1 with ~90% of the
genome at zero depth, nearly every barcode column is dropped and thousands
of lineages collapse into multi-class groups.

Changes

  • Map recombinant parents back to lineage names when loading the hierarchy,
    so either form resolves.
  • Extract per-group MRCA resolution into get_group_mrca(). A group that
    can't be resolved is now grouped into Misc with a warning instead of
    aborting. The previous except KeyError printed a message and fell
    through, leaving pango_aliases undefined (UnboundLocalError) or stale
    from the previous group, so a hierarchy behind the barcode file was never
    actually handled.
  • get_path_to_root() promoted to module level (was redefined per iteration).
  • Two regression tests using a small synthetic hierarchy, so they keep
    testing the code path if pango corrects the XHD entry upstream.

Testing

  • New tests fail on main with KeyError / UnboundLocalError, pass here.
  • flake8 clean; no change in test_utils results.

AI Disclaimer

I hit this issue and had AI help me resolve. I am fairly new to this codebase. If you are uncomfortable with this and don't have time to further investigate, feel free to close.

collapse_barcodes looks up the recombinant parents of a lineage by name in
the lineage hierarchy, but pango-designation occasionally specifies them in
unaliased form: the parents of XHD are listed as XFG.3.4.1 and
XDV.1.5.1.1.8.1, the latter being the unaliased form of NB.1.8.1. Since only
lineage names are keys of lineage_data, demixing any sample whose barcodes
collapse a group containing XHD failed with KeyError: 'XDV.1.5.1.1.8.1'.

Map recombinant parents back to lineage names when the hierarchy is loaded.

The KeyError raised when a lineage is missing from the hierarchy entirely was
also only caught for reporting, and execution then fell through to use a
pango_aliases that was undefined (or left over from the previous group), so a
hierarchy behind the barcode file raised UnboundLocalError or silently
mislabelled a group. Per-group MRCA resolution now lives in get_group_mrca,
and a group that cannot be resolved is grouped into Misc with a warning
instead of failing the run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant